iranti 0.2.11 → 0.2.12

package/README.md

@@ -245,6 +245,14 @@ iranti run --instance local
 
 If local PostgreSQL is available, setup can bootstrap a localhost database for you. If local PostgreSQL is not available, setup recommends Docker when Docker is installed, and otherwise steers you to managed PostgreSQL with concrete install guidance.
 
+If something still fails and you need more detail, use:
+
+```bash
+iranti doctor --debug
+iranti run --instance local --debug
+iranti upgrade --verbose
+```
+
 Advanced/manual path:
 
 ```bash

package/dist/scripts/iranti-cli.js

@@ -21,6 +21,15 @@ const resolutionist_1 = require("../src/resolutionist");
 const chat_1 = require("../src/chat");
 const backends_1 = require("../src/library/backends");
 const sdk_1 = require("../src/sdk");
+class CliError extends Error {
+    constructor(code, message, hints = [], details) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.hints = hints;
+        this.details = details;
+    }
+}
 const PROVIDER_ENV_KEYS = {
     mock: null,
     ollama: null,
@@ -43,6 +52,8 @@ const ANSI = {
     cyan: '\x1b[36m',
     gray: '\x1b[90m',
 };
+let CLI_DEBUG = process.argv.includes('--debug') || process.env.IRANTI_DEBUG === '1';
+let CLI_VERBOSE = CLI_DEBUG || process.argv.includes('--verbose') || process.env.IRANTI_VERBOSE === '1';
 function useColor() {
     return Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
 }
@@ -81,6 +92,25 @@ function printNextSteps(steps) {
         console.log(`  ${index + 1}. ${step}`);
     }
 }
+function setCliDebugFlags(args) {
+    CLI_DEBUG = CLI_DEBUG || hasFlag(args, 'debug');
+    CLI_VERBOSE = CLI_VERBOSE || CLI_DEBUG || hasFlag(args, 'verbose');
+}
+function debugLog(message, details) {
+    if (!CLI_DEBUG)
+        return;
+    const suffix = details && Object.keys(details).length > 0 ? ` ${JSON.stringify(details)}` : '';
+    console.log(`${paint('[DEBUG]', 'gray')} ${message}${suffix}`);
+}
+function verboseLog(message, details) {
+    if (!CLI_VERBOSE)
+        return;
+    const suffix = details && Object.keys(details).length > 0 ? ` ${JSON.stringify(details)}` : '';
+    console.log(`${paint('[TRACE]', 'gray')} ${message}${suffix}`);
+}
+function cliError(code, message, hints = [], details) {
+    return new CliError(code, message, hints, details);
+}
 function parseArgs(argv) {
     const flags = new Map();
     const positionals = [];
@@ -197,6 +227,7 @@ function formatSetupBootstrapFailure(error) {
 }
 async function handoffToScript(scriptName, rawArgs) {
     const builtPath = builtScriptPath(scriptName);
+    debugLog('Handing off to companion script.', { scriptName, builtPath, rawArgs: rawArgs.join(' ') });
     if (fs_1.default.existsSync(builtPath)) {
         await new Promise((resolve, reject) => {
             const child = (0, child_process_1.spawn)(process.execPath, [builtPath, ...rawArgs], {
@@ -219,7 +250,7 @@ async function handoffToScript(scriptName, rawArgs) {
     }
     const sourcePath = path_1.default.resolve(process.cwd(), 'scripts', `${scriptName}.ts`);
     if (!fs_1.default.existsSync(sourcePath)) {
-        throw new Error(`Unable to locate ${scriptName} implementation.`);
+        throw cliError('IRANTI_SCRIPT_NOT_FOUND', `Unable to locate ${scriptName} implementation.`, ['Run from an installed Iranti package or from the Iranti repo root where scripts/ exists.'], { scriptName, sourcePath, builtPath });
     }
     await new Promise((resolve, reject) => {
         const child = (0, child_process_1.spawn)('npx', ['ts-node', sourcePath, ...rawArgs], {
@@ -428,8 +459,12 @@ function instancePaths(root, name) {
 async function loadInstanceEnv(root, name) {
     const paths = instancePaths(root, name);
     if (!fs_1.default.existsSync(paths.envFile)) {
-        throw new Error(`Instance '${name}' not found at ${paths.instanceDir}`);
+        throw cliError('IRANTI_INSTANCE_NOT_FOUND', `Instance '${name}' not found at ${paths.instanceDir}`, [
+            'Run `iranti instance list` to see known instances.',
+            `Run \`iranti setup\` or \`iranti instance create ${name}\` if this instance does not exist yet.`,
+        ], { instance: name, root, instanceDir: paths.instanceDir });
     }
+    debugLog('Loaded instance env target.', { instance: name, envFile: paths.envFile });
     return {
         ...paths,
         env: await readEnvFile(paths.envFile),
@@ -451,15 +486,15 @@ async function resolveProviderKeyTarget(args) {
     const projectPath = path_1.default.resolve(getFlag(args, 'project') ?? process.cwd());
     const bindingFile = path_1.default.join(projectPath, '.env.iranti');
     if (!fs_1.default.existsSync(bindingFile)) {
-        throw new Error('No --instance provided and no .env.iranti found in the current project. Run from a bound project or pass --instance <name>.');
+        throw cliError('IRANTI_PROJECT_BINDING_MISSING', 'No --instance provided and no .env.iranti found in the current project.', ['Run `iranti project init . --instance <name>` or pass `--instance <name>`.'], { projectPath, bindingFile });
     }
     const binding = await readEnvFile(bindingFile);
     const envFile = binding.IRANTI_INSTANCE_ENV?.trim();
     if (!envFile) {
-        throw new Error(`Project binding is missing IRANTI_INSTANCE_ENV: ${bindingFile}`);
+        throw cliError('IRANTI_BINDING_INSTANCE_ENV_MISSING', `Project binding is missing IRANTI_INSTANCE_ENV: ${bindingFile}`, ['Run `iranti configure project` to refresh the binding.'], { bindingFile });
     }
     if (!fs_1.default.existsSync(envFile)) {
-        throw new Error(`Instance env referenced by project binding was not found: ${envFile}`);
+        throw cliError('IRANTI_BINDING_INSTANCE_ENV_NOT_FOUND', `Instance env referenced by project binding was not found: ${envFile}`, ['Run `iranti configure project` to refresh the binding or recreate the target instance.'], { bindingFile, envFile });
     }
     return {
         instanceName: binding.IRANTI_INSTANCE?.trim() || undefined,
@@ -1506,6 +1541,7 @@ function resolveDoctorEnvTarget(args) {
     const explicitEnv = getFlag(args, 'env');
     const cwd = process.cwd();
     if (explicitEnv) {
+        debugLog('Doctor target resolved from explicit env.', { envFile: path_1.default.resolve(explicitEnv) });
         return {
             envFile: path_1.default.resolve(explicitEnv),
             envSource: 'explicit-env',
@@ -1513,6 +1549,7 @@ function resolveDoctorEnvTarget(args) {
     }
     if (instanceName) {
         const root = resolveInstallRoot(args, scope);
+        debugLog('Doctor target resolved from instance.', { instance: instanceName, root });
         return {
             envFile: path_1.default.join(root, 'instances', instanceName, '.env'),
             envSource: `instance:${instanceName}`,
@@ -1521,11 +1558,14 @@ function resolveDoctorEnvTarget(args) {
     const repoEnv = path_1.default.join(cwd, '.env');
     const projectEnv = path_1.default.join(cwd, '.env.iranti');
     if (fs_1.default.existsSync(repoEnv)) {
+        debugLog('Doctor target resolved from repo env.', { envFile: repoEnv });
         return { envFile: repoEnv, envSource: 'repo' };
     }
     if (fs_1.default.existsSync(projectEnv)) {
+        debugLog('Doctor target resolved from project binding.', { envFile: projectEnv });
         return { envFile: projectEnv, envSource: 'project-binding' };
     }
+    debugLog('Doctor target resolution found no env file.', { cwd });
     return { envFile: null, envSource: 'repo' };
 }
 function resolveUpgradeTarget(raw) {
@@ -1646,6 +1686,11 @@ function quoteForCmd(arg) {
     return `"${arg.replace(/"/g, '\\"')}"`;
 }
 function runCommandCapture(executable, args, cwd, extraEnv) {
+    verboseLog('Running subprocess (capture).', {
+        executable,
+        args: args.join(' '),
+        cwd: cwd ?? process.cwd(),
+    });
     const proc = process.platform === 'win32'
         ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', [
             '/d',
@@ -1669,13 +1714,24 @@ function runCommandCapture(executable, args, cwd, extraEnv) {
                 ...extraEnv,
             },
         });
-    return {
+    const result = {
         status: proc.status,
         stdout: proc.stdout ?? '',
         stderr: proc.stderr ?? '',
     };
+    verboseLog('Subprocess finished (capture).', {
+        executable,
+        status: result.status ?? -1,
+        stderr: result.stderr.trim() || null,
+    });
+    return result;
 }
 function runCommandInteractive(step) {
+    verboseLog('Running subprocess (interactive).', {
+        label: step.label,
+        command: step.display,
+        cwd: step.cwd ?? process.cwd(),
+    });
     const proc = process.platform === 'win32'
         ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', [
             '/d',
@@ -1689,6 +1745,10 @@ function runCommandInteractive(step) {
             cwd: step.cwd,
             stdio: 'inherit',
         });
+    verboseLog('Subprocess finished (interactive).', {
+        label: step.label,
+        status: proc.status ?? -1,
+    });
     return proc.status;
 }
 function deriveDatabaseUrlForMode(mode, instanceName, explicitDatabaseUrl) {
@@ -3144,19 +3204,21 @@ async function showInstanceCommand(args) {
 }
 async function runInstanceCommand(args) {
     const name = getFlag(args, 'instance') ?? args.positionals[0] ?? args.subcommand;
-    if (!name)
-        throw new Error('Missing instance name. Usage: iranti run --instance <name>');
+    if (!name) {
+        throw cliError('IRANTI_INSTANCE_NAME_REQUIRED', 'Missing instance name. Usage: iranti run --instance <name>', ['Run `iranti instance list` to see configured instances.']);
+    }
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
     const envFile = path_1.default.join(root, 'instances', name, '.env');
-    if (!fs_1.default.existsSync(envFile))
-        throw new Error(`Instance '${name}' not found. Create it first.`);
+    if (!fs_1.default.existsSync(envFile)) {
+        throw cliError('IRANTI_INSTANCE_NOT_FOUND', `Instance '${name}' not found. Create it first.`, [`Run \`iranti setup\` or \`iranti instance create ${name}\` first.`], { instance: name, envFile });
+    }
     const env = await readEnvFile(envFile);
     for (const [k, v] of Object.entries(env)) {
         process.env[k] = v;
     }
     if (!process.env.DATABASE_URL || process.env.DATABASE_URL.includes('yourpassword')) {
-        throw new Error(`Instance '${name}' has placeholder DATABASE_URL. Edit ${envFile} first.`);
+        throw cliError('IRANTI_INSTANCE_DATABASE_PLACEHOLDER', `Instance '${name}' has placeholder DATABASE_URL. Edit ${envFile} first.`, ['Run `iranti configure instance <name> --interactive` or rerun `iranti setup`.'], { instance: name, envFile });
     }
     console.log(`${infoLabel()} Starting Iranti instance '${name}' on port ${process.env.IRANTI_PORT ?? '3001'}...`);
     const serverEntry = path_1.default.resolve(__dirname, '..', 'src', 'api', 'server');
@@ -3167,7 +3229,7 @@ async function projectInitCommand(args) {
     const projectPath = path_1.default.resolve(args.positionals[0] ?? process.cwd());
     const instanceName = getFlag(args, 'instance');
     if (!instanceName) {
-        throw new Error('Missing --instance <name>. Usage: iranti project init [path] --instance <name>');
+        throw cliError('IRANTI_INSTANCE_NAME_REQUIRED', 'Missing --instance <name>. Usage: iranti project init [path] --instance <name>', ['Run `iranti instance list` to see available instances.']);
     }
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
@@ -3178,7 +3240,7 @@ async function projectInitCommand(args) {
     const projectMode = normalizeProjectMode(getFlag(args, 'mode'), 'isolated');
     const outFile = path_1.default.join(projectPath, '.env.iranti');
     if (fs_1.default.existsSync(outFile) && !hasFlag(args, 'force')) {
-        throw new Error(`${outFile} already exists. Use --force to overwrite.`);
+        throw cliError('IRANTI_PROJECT_BINDING_EXISTS', `${outFile} already exists. Use --force to overwrite.`, ['Use `iranti configure project` if you want to refresh the existing binding instead.'], { outFile });
     }
     await writeProjectBinding(projectPath, {
         IRANTI_URL: `http://localhost:${port}`,
@@ -3633,7 +3695,7 @@ async function claudeSetupCommand(args) {
             ?? (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}`);
+            throw cliError('IRANTI_SCAN_PATH_NOT_FOUND', `Scan directory not found: ${scanDir}`);
         }
         const candidates = findClaudeProjects(scanDir, recursive);
         if (candidates.length === 0) {
@@ -3680,10 +3742,10 @@ async function claudeSetupCommand(args) {
         ? 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}`);
+        throw cliError('IRANTI_PROJECT_PATH_NOT_FOUND', `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.`);
+        throw cliError('IRANTI_PROJECT_BINDING_MISSING', `Project binding not found at ${projectEnvPath}. Run \`iranti project init\` or \`iranti configure project\` first.`, ['Run `iranti project init . --instance <name>` before `iranti claude-setup`.'], { projectEnvPath });
     }
     const result = await writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force);
     console.log(`${okLabel()} Claude Code integration scaffolded`);
@@ -3725,6 +3787,7 @@ function printHelp() {
     console.log(sectionTitle('Iranti CLI'));
     console.log('Memory infrastructure for multi-agent systems.');
     console.log('Most instance-aware commands also accept --root <path> in addition to --scope.');
+    console.log('Global debugging flags: --debug for extra diagnostics, --verbose for subprocess trace output.');
     console.log('');
     printRows('Start Here', rows);
     printRows('Setup And Runtime', [
@@ -3750,7 +3813,7 @@ function printHelp() {
         ['iranti remove api-key [provider] [--instance <name>] [--project <path>] [--json]', 'Remove a stored provider key.'],
     ]);
     printRows('Diagnostics And Operator Tools', [
-        ['iranti doctor [--instance <name>] [--scope user|system] [--env <file>] [--json]', 'Run environment and runtime diagnostics.'],
+        ['iranti doctor [--instance <name>] [--scope user|system] [--env <file>] [--json] [--debug]', 'Run environment and runtime diagnostics.'],
         ['iranti status [--scope user|system] [--json]', 'Show runtime roots, bindings, and known instances.'],
         ['iranti upgrade [--check] [--dry-run] [--yes] [--all] [--target auto|npm-global|npm-repo|python[,python]] [--json]', 'Check or run CLI/runtime/package upgrades.'],
         ['iranti handshake [--instance <name> | --project-env <file>] [--agent <id>] [--task <text>] [--recent <msg1||msg2>] [--recent-file <path>] [--json]', 'Manually inspect Attendant handshake output.'],
@@ -3825,6 +3888,12 @@ function printProviderKeyHelp() {
 }
 async function main() {
     const args = parseArgs(process.argv.slice(2));
+    setCliDebugFlags(args);
+    debugLog('CLI invocation started.', {
+        command: args.command,
+        subcommand: args.subcommand,
+        cwd: process.cwd(),
+    });
     if (!args.command || args.command === 'help' || args.command === '--help') {
         printHelp();
         return;
@@ -3993,11 +4062,27 @@ async function main() {
         }
         throw new Error(`Unknown integrate target '${args.subcommand ?? ''}'. Use 'claude' or 'codex'.`);
     }
-    throw new Error(`Unknown command '${args.command}'. Run: iranti help`);
+    throw cliError('IRANTI_UNKNOWN_COMMAND', `Unknown command '${args.command}'. Run: iranti help`, ['Use `iranti help` to see the current command surface.'], { command: args.command });
 }
 main().catch((err) => {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`${failLabel('ERROR')} ${message}`);
+    const code = err instanceof CliError ? err.code : null;
+    console.error(`${failLabel('ERROR')}${code ? ` [${code}]` : ''} ${message}`);
+    if (err instanceof CliError && err.hints.length > 0) {
+        console.error('');
+        console.error('Possible fixes:');
+        for (const hint of err.hints) {
+            console.error(`  - ${hint}`);
+        }
+    }
+    if (CLI_DEBUG && err instanceof CliError && err.details && Object.keys(err.details).length > 0) {
+        console.error('');
+        console.error(`${paint('[DEBUG]', 'gray')} ${JSON.stringify(err.details, null, 2)}`);
+    }
+    if (CLI_DEBUG && err instanceof Error && err.stack) {
+        console.error('');
+        console.error(err.stack);
+    }
     process.exit(1);
 });
 //# sourceMappingURL=iranti-cli.js.map

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.11',
+        version: '0.2.12',
     });
     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.11',
+            version: '0.2.12',
             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.11',
+            version: '0.2.12',
             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.11',
+            version: '0.2.12',
             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.11' },
+        valueRaw: { version: '0.2.12' },
         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.11',
+            seedVersion: '0.2.12',
         },
         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.11',
+            version: '0.2.12',
             states: ['candidate', 'provisional', 'canonical'],
             coreEntityTypes: [
                 'person',
@@ -156,7 +156,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'extension_registry',
         valueRaw: {
-            version: '0.2.11',
+            version: '0.2.12',
             namespaces: {
                 education: {
                     status: 'provisional',
@@ -187,7 +187,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'candidate_terms',
         valueRaw: {
-            version: '0.2.11',
+            version: '0.2.12',
             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.11',
+            version: '0.2.12',
             candidateToProvisional: {
                 minSeenCount: 3,
                 minDistinctAgents: 2,
@@ -237,7 +237,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'change_log',
         valueRaw: {
-            version: '0.2.11',
+            version: '0.2.12',
             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.11',
+        version: '0.2.12',
         provider: process.env.LLM_PROVIDER ?? 'mock',
     });
 });

package/package.json

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