meetsoma 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to Soma (`meetsoma` on npm).
 
 Format follows [Keep a Changelog](https://keepachangelog.com/). Versioning follows [Semantic Versioning](https://semver.org/).
 
+## [0.3.2] — 2026-04-10
+
+### Fixed
+- **Health check warnings**: now shows "passed (N warnings)" instead of silent "All checks passed" when warnings exist
+
 ## [0.3.1] — 2026-04-10
 
 Re-release of 0.3.0 (npm doesn't allow republish of unpublished versions).

package/dist/thin-cli.js

@@ -29,6 +29,19 @@ import { showAbout } from "./welcome/about.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
 
+// Semver comparison: returns -1 (a<b), 0 (equal), 1 (a>b)
+function semverCmp(a, b) {
+  if (!a || !b) return 0;
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const va = pa[i] || 0, vb = pb[i] || 0;
+    if (va < vb) return -1;
+    if (va > vb) return 1;
+  }
+  return 0;
+}
+
 // ── Welcome / First Run ─────────────────────────────────────────────
 
 async function showWelcome() {
@@ -198,6 +211,20 @@ async function initSoma() {
       }
     }
 
+    // Preserve user-installed extensions (non-soma-* files)
+    const extDir = join(installDir, "extensions");
+    if (existsSync(extDir)) {
+      try {
+        for (const f of readdirSync(extDir).filter(f => !f.startsWith("soma-") && (f.endsWith(".ts") || f.endsWith(".js")))) {
+          const fp = join(extDir, f);
+          try {
+            preservedFiles[`extensions/${f}`] = readFileSync(fp, "utf-8");
+            console.log(`  ${dim("→")} Preserving extension: ${f}`);
+          } catch {}
+        }
+      } catch {}
+    }
+
     const hasGit = existsSync(join(installDir, ".git"));
     let repaired = false;
 
@@ -342,7 +369,7 @@ async function checkAndUpdate() {
 
     const agentV = getAgentVersion();
     const projectV = getProjectVersion();
-    if (agentV && projectV && projectV < agentV) {
+    if (agentV && projectV && semverCmp(projectV, agentV) < 0) {
       console.log(`  ${yellow("⚠")} Project .soma/ is at ${cyan(`v${projectV}`)}, agent is at ${cyan(`v${agentV}`)}.`);
       console.log(`  Run ${green("soma doctor")} to check for updates.`);
     }
@@ -473,13 +500,14 @@ async function healthCheck() {
   console.log("");
 
   let issues = 0;
+  let warnings = 0;
   const check = (ok, pass, fail_msg) => {
     if (ok) { console.log(`  ${green("✓")} ${pass}`); }
     else { console.log(`  ${red("✗")} ${fail_msg}`); issues++; }
   };
   const warn = (ok, pass, fail_msg) => {
     if (ok) { console.log(`  ${green("✓")} ${pass}`); }
-    else { console.log(`  ${yellow("⚠")} ${fail_msg}`); }
+    else { console.log(`  ${yellow("⚠")} ${fail_msg}`); warnings++; }
   };
 
   const nodeVersion = process.versions.node;
@@ -549,10 +577,12 @@ async function healthCheck() {
   }
 
   console.log("");
-  if (issues === 0) {
+  if (issues === 0 && warnings === 0) {
     console.log(`  ${green("✓ All checks passed")}`);
+  } else if (issues === 0) {
+    console.log(`  ${green("✓ All checks passed")} ${dim(`(${warnings} warning${warnings > 1 ? "s" : ""})`)}`);  
   } else {
-    console.log(`  ${yellow(`${issues} issue${issues > 1 ? "s" : ""} found`)}`);
+    console.log(`  ${yellow(`${issues} issue${issues > 1 ? "s" : ""} found`)}${warnings > 0 ? dim(` + ${warnings} warning${warnings > 1 ? "s" : ""}`) : ""}`);
     console.log(`  ${voice.say("suggest", { suggestion: issues > 2 ? "start with soma init" : "check the items above" })}`);
   }
   console.log("");
@@ -609,14 +639,14 @@ async function projectDoctor() {
     return;
   }
 
-  if (agentV && projectV === agentV) {
+  if (agentV && semverCmp(projectV, agentV) === 0) {
     console.log(`  ${green("✓")} Project is up to date.`);
     console.log("");
     await healthCheck();
     return;
   }
   
-  if (agentV && projectV < agentV) {
+  if (agentV && semverCmp(projectV, agentV) < 0) {
     console.log(`  ${yellow("⚠")} Project .soma/ is at ${cyan(`v${projectV}`)} , agent is at ${cyan(`v${agentV}`)} .`);
     console.log("");
   
@@ -648,18 +678,19 @@ async function projectDoctor() {
       const realCore = readlinkSync(join(CORE_DIR, "core"));
       if (realCore) {
         const devRoot = dirname(realCore);
-        if (existsSync(join(devRoot, "body", "_public"))) agentRoot = devRoot;
+        if (existsSync(join(devRoot, "templates", "default")) || existsSync(join(devRoot, "body", "_public"))) agentRoot = devRoot;
       }
     } catch {}
-    if (!existsSync(join(agentRoot, "body", "_public"))) {
-      const parent = dirname(agentRoot);
-      if (existsSync(join(parent, "body", "_public"))) agentRoot = parent;
-    }
-    const bundledBody = join(agentRoot, "body", "_public");
-    if (existsSync(bundledBody)) {
+    // Resolve bundled body templates: templates/default/ (v0.11+) or body/_public/ (legacy)
+    const bundledBody = existsSync(join(agentRoot, "templates", "default"))
+      ? join(agentRoot, "templates", "default")
+      : existsSync(join(agentRoot, "body", "_public"))
+        ? join(agentRoot, "body", "_public")
+        : null;
+    if (bundledBody && existsSync(bundledBody)) {
       try {
         if (!existsSync(bodyDir)) mkdirSync(bodyDir, { recursive: true });
-        for (const f of readdirSync(bundledBody).filter(f => f.endsWith(".md"))) {
+        for (const f of readdirSync(bundledBody).filter(f => f.endsWith(".md") && !f.startsWith("_"))) {
           const dest = join(bodyDir, f);
           if (!existsSync(dest)) { writeFileSync(dest, readFileSync(join(bundledBody, f), "utf-8")); fixes++; }
         }
@@ -858,9 +889,19 @@ async function delegateToCore() {
 const args = process.argv.slice(2);
 const cmd = args[0];
 
-if (cmd === "--version" || cmd === "-v" || cmd === "-V") {
+// Keep config.json coreVersion fresh — cheap check, prevents staleness
+try {
+  const config = readConfig();
+  const currentV = getAgentVersion();
+  if (currentV && config.coreVersion !== currentV) {
+    config.coreVersion = currentV;
+    writeConfig(config);
+  }
+} catch {}
+
+if (cmd === "--version" || cmd === "-v" || cmd === "-V" || cmd === "version") {
   showVersion();
-} else if (cmd === "--help" || cmd === "-h") {
+} else if (cmd === "--help" || cmd === "-h" || cmd === "help") {
   if (isInstalled()) {
     await delegateToCore();
   } else {
@@ -886,6 +927,11 @@ if (cmd === "--version" || cmd === "-v" || cmd === "-V") {
   await projectDoctor();
 } else if (cmd === "status" || cmd === "health") {
   await healthCheck();
+} else if (cmd && cmd.startsWith("--") && !isInstalled()) {
+  // Unknown flag before install — show help
+  console.log(`  ${yellow("⚠")} Unknown option: ${cmd}`);
+  console.log(`  Run ${green("soma --help")} for usage.`);
+  console.log("");
 } else if (isInstalled()) {
   await delegateToCore();
 } else {

package/package.json

@@ -1,91 +1,44 @@
 {
-	"name": "meetsoma",
-	"version": "0.3.1",
-	"description": "AI coding agent with self-growing memory — identity, protocols, and muscles that evolve with use",
-	"type": "module",
-	"piConfig": {
-		"name": "soma",
-		"configDir": ".soma"
-	},
-	"bin": {
-		"soma": "dist/cli.js"
-	},
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
-		"./hooks": {
-			"types": "./dist/core/hooks/index.d.ts",
-			"import": "./dist/core/hooks/index.js"
-		}
-	},
-	"files": [
-		"dist",
-		"bin",
-		"scripts/install-gum.sh",
-		"CHANGELOG.md"
-	],
-	"dependencies": {
-		"@mariozechner/jiti": "^2.6.5",
-		"@mariozechner/pi-agent-core": "^0.64.0",
-		"@mariozechner/pi-ai": "^0.64.0",
-		"@mariozechner/pi-tui": "^0.64.0",
-		"@silvia-odwyer/photon-node": "^0.3.4",
-		"@sinclair/typebox": "^0.34.48",
-		"chalk": "^5.5.0",
-		"cli-highlight": "^2.1.11",
-		"diff": "^8.0.2",
-		"extract-zip": "^2.0.1",
-		"file-type": "^21.1.1",
-		"glob": "^13.0.1",
-		"hosted-git-info": "^9.0.2",
-		"ignore": "^7.0.5",
-		"marked": "^15.0.12",
-		"minimatch": "^10.2.3",
-		"proper-lockfile": "^4.1.2",
-		"strip-ansi": "^7.1.0",
-		"undici": "^7.19.1",
-		"yaml": "^2.8.2"
-	},
-	"overrides": {
-		"rimraf": "6.1.2",
-		"gaxios": {
-			"rimraf": "6.1.2"
-		}
-	},
-	"optionalDependencies": {
-		"@mariozechner/clipboard": "^0.3.2"
-	},
-	"keywords": [
-		"soma",
-		"meetsoma",
-		"ai",
-		"agent",
-		"memory",
-		"coding-agent",
-		"identity",
-		"muscles",
-		"protocols",
-		"self-evolving",
-		"cli",
-		"llm",
-		"persistence",
-		"session"
-	],
-	"author": "Gravicity <hello@gravicity.ai>",
-	"license": "BSL-1.1",
-	"homepage": "https://soma.gravicity.ai",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/meetsoma/soma-agent.git"
-	},
-	"engines": {
-		"node": ">=20.6.0"
-	},
-	"scripts": {
-		"postinstall": "bash scripts/install-gum.sh || true"
-	}
+  "name": "meetsoma",
+  "version": "0.3.3",
+  "description": "Soma — the AI coding agent with self-growing memory",
+  "type": "module",
+  "bin": {
+    "soma": "dist/thin-cli.js"
+  },
+  "files": [
+    "dist/thin-cli.js",
+    "dist/personality.js",
+    "dist/postinstall.js",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "soma",
+    "meetsoma",
+    "ai",
+    "agent",
+    "memory",
+    "coding-agent",
+    "identity",
+    "muscles",
+    "protocols",
+    "self-evolving",
+    "cli",
+    "llm"
+  ],
+  "author": "Gravicity <hello@gravicity.ai>",
+  "license": "BSL-1.1",
+  "homepage": "https://soma.gravicity.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meetsoma/soma-agent.git"
+  },
+  "scripts": {
+    "postinstall": "node dist/postinstall.js"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
 }

package/dist/bun/cli.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/bun/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/bun/cli.ts"],"names":[],"mappings":"","sourcesContent":["#!/usr/bin/env node\nprocess.title = \"pi\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\nawait import(\"./register-bedrock.js\");\nawait import(\"../cli.js\");\n"]}

package/dist/bun/cli.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-process.title = "pi";
-process.emitWarning = (() => { });
-await import("./register-bedrock.js");
-await import("../cli.js");
-export {};
-//# sourceMappingURL=cli.js.map

package/dist/bun/cli.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/bun/cli.ts"],"names":[],"mappings":";AACA,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;AACrB,OAAO,CAAC,WAAW,GAAG,CAAC,GAAG,EAAE,CAAC,EAAC,CAAC,CAA+B,CAAC;AAE/D,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;AACtC,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nprocess.title = \"pi\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\nawait import(\"./register-bedrock.js\");\nawait import(\"../cli.js\");\n"]}

package/dist/bun/register-bedrock.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=register-bedrock.d.ts.map

package/dist/bun/register-bedrock.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"register-bedrock.d.ts","sourceRoot":"","sources":["../../src/bun/register-bedrock.ts"],"names":[],"mappings":"","sourcesContent":["import { setBedrockProviderModule } from \"@mariozechner/pi-ai\";\nimport { bedrockProviderModule } from \"@mariozechner/pi-ai/bedrock-provider\";\n\nsetBedrockProviderModule(bedrockProviderModule);\n"]}

package/dist/bun/register-bedrock.js

@@ -1,4 +0,0 @@
-import { setBedrockProviderModule } from "@mariozechner/pi-ai";
-import { bedrockProviderModule } from "@mariozechner/pi-ai/bedrock-provider";
-setBedrockProviderModule(bedrockProviderModule);
-//# sourceMappingURL=register-bedrock.js.map

package/dist/bun/register-bedrock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"register-bedrock.js","sourceRoot":"","sources":["../../src/bun/register-bedrock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAE7E,wBAAwB,CAAC,qBAAqB,CAAC,CAAC","sourcesContent":["import { setBedrockProviderModule } from \"@mariozechner/pi-ai\";\nimport { bedrockProviderModule } from \"@mariozechner/pi-ai/bedrock-provider\";\n\nsetBedrockProviderModule(bedrockProviderModule);\n"]}

package/dist/cli/args.d.ts

@@ -1,49 +0,0 @@
-/**
- * CLI argument parsing and help display
- */
-import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
-import { type ToolName } from "../core/tools/index.js";
-export type Mode = "text" | "json" | "rpc";
-export interface Args {
-    provider?: string;
-    model?: string;
-    apiKey?: string;
-    systemPrompt?: string;
-    appendSystemPrompt?: string;
-    thinking?: ThinkingLevel;
-    continue?: boolean;
-    resume?: boolean;
-    help?: boolean;
-    version?: boolean;
-    mode?: Mode;
-    noSession?: boolean;
-    session?: string;
-    fork?: string;
-    sessionDir?: string;
-    models?: string[];
-    tools?: ToolName[];
-    noTools?: boolean;
-    extensions?: string[];
-    noExtensions?: boolean;
-    print?: boolean;
-    export?: string;
-    noSkills?: boolean;
-    skills?: string[];
-    promptTemplates?: string[];
-    noPromptTemplates?: boolean;
-    themes?: string[];
-    noThemes?: boolean;
-    listModels?: string | true;
-    offline?: boolean;
-    verbose?: boolean;
-    messages: string[];
-    fileArgs: string[];
-    /** Unknown flags (potentially extension flags) - map of flag name to value */
-    unknownFlags: Map<string, boolean | string>;
-}
-export declare function isValidThinkingLevel(level: string): level is ThinkingLevel;
-export declare function parseArgs(args: string[], extensionFlags?: Map<string, {
-    type: "boolean" | "string";
-}>): Args;
-export declare function printHelp(): void;
-//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEjE,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,IAAI;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8EAA8E;IAC9E,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;CAC5C;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAE1E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,CAAC,GAAG,IAAI,CA4H5G;AAED,wBAAgB,SAAS,IAAI,IAAI,CA2IhC","sourcesContent":["/**\n * CLI argument parsing and help display\n */\n\nimport type { ThinkingLevel } from \"@mariozechner/pi-agent-core\";\nimport chalk from \"chalk\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from \"../config.js\";\nimport { allTools, type ToolName } from \"../core/tools/index.js\";\n\nexport type Mode = \"text\" | \"json\" | \"rpc\";\n\nexport interface Args {\n\tprovider?: string;\n\tmodel?: string;\n\tapiKey?: string;\n\tsystemPrompt?: string;\n\tappendSystemPrompt?: string;\n\tthinking?: ThinkingLevel;\n\tcontinue?: boolean;\n\tresume?: boolean;\n\thelp?: boolean;\n\tversion?: boolean;\n\tmode?: Mode;\n\tnoSession?: boolean;\n\tsession?: string;\n\tfork?: string;\n\tsessionDir?: string;\n\tmodels?: string[];\n\ttools?: ToolName[];\n\tnoTools?: boolean;\n\textensions?: string[];\n\tnoExtensions?: boolean;\n\tprint?: boolean;\n\texport?: string;\n\tnoSkills?: boolean;\n\tskills?: string[];\n\tpromptTemplates?: string[];\n\tnoPromptTemplates?: boolean;\n\tthemes?: string[];\n\tnoThemes?: boolean;\n\tlistModels?: string | true;\n\toffline?: boolean;\n\tverbose?: boolean;\n\tmessages: string[];\n\tfileArgs: string[];\n\t/** Unknown flags (potentially extension flags) - map of flag name to value */\n\tunknownFlags: Map<string, boolean | string>;\n}\n\nconst VALID_THINKING_LEVELS = [\"off\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\"] as const;\n\nexport function isValidThinkingLevel(level: string): level is ThinkingLevel {\n\treturn VALID_THINKING_LEVELS.includes(level as ThinkingLevel);\n}\n\nexport function parseArgs(args: string[], extensionFlags?: Map<string, { type: \"boolean\" | \"string\" }>): Args {\n\tconst result: Args = {\n\t\tmessages: [],\n\t\tfileArgs: [],\n\t\tunknownFlags: new Map(),\n\t};\n\n\tfor (let i = 0; i < args.length; i++) {\n\t\tconst arg = args[i];\n\n\t\tif (arg === \"--help\" || arg === \"-h\") {\n\t\t\tresult.help = true;\n\t\t} else if (arg === \"--version\" || arg === \"-v\") {\n\t\t\tresult.version = true;\n\t\t} else if (arg === \"--mode\" && i + 1 < args.length) {\n\t\t\tconst mode = args[++i];\n\t\t\tif (mode === \"text\" || mode === \"json\" || mode === \"rpc\") {\n\t\t\t\tresult.mode = mode;\n\t\t\t}\n\t\t} else if (arg === \"--continue\" || arg === \"-c\") {\n\t\t\tresult.continue = true;\n\t\t} else if (arg === \"--resume\" || arg === \"-r\") {\n\t\t\tresult.resume = true;\n\t\t} else if (arg === \"--provider\" && i + 1 < args.length) {\n\t\t\tresult.provider = args[++i];\n\t\t} else if (arg === \"--model\" && i + 1 < args.length) {\n\t\t\tresult.model = args[++i];\n\t\t} else if (arg === \"--api-key\" && i + 1 < args.length) {\n\t\t\tresult.apiKey = args[++i];\n\t\t} else if (arg === \"--system-prompt\" && i + 1 < args.length) {\n\t\t\tresult.systemPrompt = args[++i];\n\t\t} else if (arg === \"--append-system-prompt\" && i + 1 < args.length) {\n\t\t\tresult.appendSystemPrompt = args[++i];\n\t\t} else if (arg === \"--no-session\") {\n\t\t\tresult.noSession = true;\n\t\t} else if (arg === \"--session\" && i + 1 < args.length) {\n\t\t\tresult.session = args[++i];\n\t\t} else if (arg === \"--fork\" && i + 1 < args.length) {\n\t\t\tresult.fork = args[++i];\n\t\t} else if (arg === \"--session-dir\" && i + 1 < args.length) {\n\t\t\tresult.sessionDir = args[++i];\n\t\t} else if (arg === \"--models\" && i + 1 < args.length) {\n\t\t\tresult.models = args[++i].split(\",\").map((s) => s.trim());\n\t\t} else if (arg === \"--no-tools\") {\n\t\t\tresult.noTools = true;\n\t\t} else if (arg === \"--tools\" && i + 1 < args.length) {\n\t\t\tconst toolNames = args[++i].split(\",\").map((s) => s.trim());\n\t\t\tconst validTools: ToolName[] = [];\n\t\t\tfor (const name of toolNames) {\n\t\t\t\tif (name in allTools) {\n\t\t\t\t\tvalidTools.push(name as ToolName);\n\t\t\t\t} else {\n\t\t\t\t\tconsole.error(\n\t\t\t\t\t\tchalk.yellow(`Warning: Unknown tool \"${name}\". Valid tools: ${Object.keys(allTools).join(\", \")}`),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tresult.tools = validTools;\n\t\t} else if (arg === \"--thinking\" && i + 1 < args.length) {\n\t\t\tconst level = args[++i];\n\t\t\tif (isValidThinkingLevel(level)) {\n\t\t\t\tresult.thinking = level;\n\t\t\t} else {\n\t\t\t\tconsole.error(\n\t\t\t\t\tchalk.yellow(\n\t\t\t\t\t\t`Warning: Invalid thinking level \"${level}\". Valid values: ${VALID_THINKING_LEVELS.join(\", \")}`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t} else if (arg === \"--print\" || arg === \"-p\") {\n\t\t\tresult.print = true;\n\t\t} else if (arg === \"--export\" && i + 1 < args.length) {\n\t\t\tresult.export = args[++i];\n\t\t} else if ((arg === \"--extension\" || arg === \"-e\") && i + 1 < args.length) {\n\t\t\tresult.extensions = result.extensions ?? [];\n\t\t\tresult.extensions.push(args[++i]);\n\t\t} else if (arg === \"--no-extensions\" || arg === \"-ne\") {\n\t\t\tresult.noExtensions = true;\n\t\t} else if (arg === \"--skill\" && i + 1 < args.length) {\n\t\t\tresult.skills = result.skills ?? [];\n\t\t\tresult.skills.push(args[++i]);\n\t\t} else if (arg === \"--prompt-template\" && i + 1 < args.length) {\n\t\t\tresult.promptTemplates = result.promptTemplates ?? [];\n\t\t\tresult.promptTemplates.push(args[++i]);\n\t\t} else if (arg === \"--theme\" && i + 1 < args.length) {\n\t\t\tresult.themes = result.themes ?? [];\n\t\t\tresult.themes.push(args[++i]);\n\t\t} else if (arg === \"--no-skills\" || arg === \"-ns\") {\n\t\t\tresult.noSkills = true;\n\t\t} else if (arg === \"--no-prompt-templates\" || arg === \"-np\") {\n\t\t\tresult.noPromptTemplates = true;\n\t\t} else if (arg === \"--no-themes\") {\n\t\t\tresult.noThemes = true;\n\t\t} else if (arg === \"--list-models\") {\n\t\t\t// Check if next arg is a search pattern (not a flag or file arg)\n\t\t\tif (i + 1 < args.length && !args[i + 1].startsWith(\"-\") && !args[i + 1].startsWith(\"@\")) {\n\t\t\t\tresult.listModels = args[++i];\n\t\t\t} else {\n\t\t\t\tresult.listModels = true;\n\t\t\t}\n\t\t} else if (arg === \"--verbose\") {\n\t\t\tresult.verbose = true;\n\t\t} else if (arg === \"--offline\") {\n\t\t\tresult.offline = true;\n\t\t} else if (arg.startsWith(\"@\")) {\n\t\t\tresult.fileArgs.push(arg.slice(1)); // Remove @ prefix\n\t\t} else if (arg.startsWith(\"--\") && extensionFlags) {\n\t\t\t// Check if it's an extension-registered flag\n\t\t\tconst flagName = arg.slice(2);\n\t\t\tconst extFlag = extensionFlags.get(flagName);\n\t\t\tif (extFlag) {\n\t\t\t\tif (extFlag.type === \"boolean\") {\n\t\t\t\t\tresult.unknownFlags.set(flagName, true);\n\t\t\t\t} else if (extFlag.type === \"string\" && i + 1 < args.length) {\n\t\t\t\t\tresult.unknownFlags.set(flagName, args[++i]);\n\t\t\t\t}\n\t\t\t}\n\t\t\t// Unknown flags without extensionFlags are silently ignored (first pass)\n\t\t} else if (!arg.startsWith(\"-\")) {\n\t\t\tresult.messages.push(arg);\n\t\t}\n\t}\n\n\treturn result;\n}\n\nexport function printHelp(): void {\n\tconsole.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools\n\n${chalk.bold(\"Usage:\")}\n  ${APP_NAME} [options] [@files...] [messages...]\n\n${chalk.bold(\"Commands:\")}\n  ${APP_NAME} install <source> [-l]     Install extension source and add to settings\n  ${APP_NAME} remove <source> [-l]      Remove extension source from settings\n  ${APP_NAME} uninstall <source> [-l]   Alias for remove\n  ${APP_NAME} update [source]           Update installed extensions (skips pinned sources)\n  ${APP_NAME} list                      List installed extensions from settings\n  ${APP_NAME} config                    Open TUI to enable/disable package resources\n  ${APP_NAME} <command> --help          Show help for install/remove/uninstall/update/list\n\n${chalk.bold(\"Options:\")}\n  --provider <name>              Provider name (default: google)\n  --model <pattern>              Model pattern or ID (supports \"provider/id\" and optional \":<thinking>\")\n  --api-key <key>                API key (defaults to env vars)\n  --system-prompt <text>         System prompt (default: coding assistant prompt)\n  --append-system-prompt <text>  Append text or file contents to the system prompt\n  --mode <mode>                  Output mode: text (default), json, or rpc\n  --print, -p                    Non-interactive mode: process prompt and exit\n  --continue, -c                 Continue previous session\n  --resume, -r                   Select a session to resume\n  --session <path>               Use specific session file\n  --fork <path>                  Fork specific session file or partial UUID into a new session\n  --session-dir <dir>            Directory for session storage and lookup\n  --no-session                   Don't save session (ephemeral)\n  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling\n                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching\n  --no-tools                     Disable all built-in tools\n  --tools <tools>                Comma-separated list of tools to enable (default: read,bash,edit,write)\n                                 Available: read, bash, edit, write, grep, find, ls\n  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh\n  --extension, -e <path>         Load an extension file (can be used multiple times)\n  --no-extensions, -ne           Disable extension discovery (explicit -e paths still work)\n  --skill <path>                 Load a skill file or directory (can be used multiple times)\n  --no-skills, -ns               Disable skills discovery and loading\n  --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)\n  --no-prompt-templates, -np     Disable prompt template discovery and loading\n  --theme <path>                 Load a theme file or directory (can be used multiple times)\n  --no-themes                    Disable theme discovery and loading\n  --export <file>                Export session file to HTML and exit\n  --list-models [search]         List available models (with optional fuzzy search)\n  --verbose                      Force verbose startup (overrides quietStartup setting)\n  --offline                      Disable startup network operations (same as PI_OFFLINE=1)\n  --help, -h                     Show this help\n  --version, -v                  Show version number\n\nExtensions can register additional flags (e.g., --plan from plan-mode extension).\n\n${chalk.bold(\"Examples:\")}\n  # Interactive mode\n  ${APP_NAME}\n\n  # Interactive mode with initial prompt\n  ${APP_NAME} \"List all .ts files in src/\"\n\n  # Include files in initial message\n  ${APP_NAME} @prompt.md @image.png \"What color is the sky?\"\n\n  # Non-interactive mode (process and exit)\n  ${APP_NAME} -p \"List all .ts files in src/\"\n\n  # Multiple messages (interactive)\n  ${APP_NAME} \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  ${APP_NAME} --continue \"What did we discuss?\"\n\n  # Use different model\n  ${APP_NAME} --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Use model with provider prefix (no --provider needed)\n  ${APP_NAME} --model openai/gpt-4o \"Help me refactor this code\"\n\n  # Use model with thinking level shorthand\n  ${APP_NAME} --model sonnet:high \"Solve this complex problem\"\n\n  # Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o\n\n  # Limit to a specific provider with glob pattern\n  ${APP_NAME} --models \"github-copilot/*\"\n\n  # Cycle models with fixed thinking levels\n  ${APP_NAME} --models sonnet:high,haiku:low\n\n  # Start with a specific thinking level\n  ${APP_NAME} --thinking high \"Solve this complex problem\"\n\n  # Read-only mode (no file modifications possible)\n  ${APP_NAME} --tools read,grep,find,ls -p \"Review the code in src/\"\n\n  # Export a session file to HTML\n  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl\n  ${APP_NAME} --export session.jsonl output.html\n\n${chalk.bold(\"Environment Variables:\")}\n  ANTHROPIC_API_KEY                - Anthropic Claude API key\n  ANTHROPIC_OAUTH_TOKEN            - Anthropic OAuth token (alternative to API key)\n  OPENAI_API_KEY                   - OpenAI GPT API key\n  AZURE_OPENAI_API_KEY             - Azure OpenAI API key\n  AZURE_OPENAI_BASE_URL            - Azure OpenAI base URL (https://{resource}.openai.azure.com/openai/v1)\n  AZURE_OPENAI_RESOURCE_NAME       - Azure OpenAI resource name (alternative to base URL)\n  AZURE_OPENAI_API_VERSION         - Azure OpenAI API version (default: v1)\n  AZURE_OPENAI_DEPLOYMENT_NAME_MAP - Azure OpenAI model=deployment map (comma-separated)\n  GEMINI_API_KEY                   - Google Gemini API key\n  GROQ_API_KEY                     - Groq API key\n  CEREBRAS_API_KEY                 - Cerebras API key\n  XAI_API_KEY                      - xAI Grok API key\n  OPENROUTER_API_KEY               - OpenRouter API key\n  AI_GATEWAY_API_KEY               - Vercel AI Gateway API key\n  ZAI_API_KEY                      - ZAI API key\n  MISTRAL_API_KEY                  - Mistral API key\n  MINIMAX_API_KEY                  - MiniMax API key\n  OPENCODE_API_KEY                 - OpenCode Zen/OpenCode Go API key\n  KIMI_API_KEY                     - Kimi For Coding API key\n  AWS_PROFILE                      - AWS profile for Amazon Bedrock\n  AWS_ACCESS_KEY_ID                - AWS access key for Amazon Bedrock\n  AWS_SECRET_ACCESS_KEY            - AWS secret key for Amazon Bedrock\n  AWS_BEARER_TOKEN_BEDROCK         - Bedrock API key (bearer token)\n  AWS_REGION                       - AWS region for Amazon Bedrock (e.g., us-east-1)\n  ${ENV_AGENT_DIR.padEnd(32)} - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)\n  PI_PACKAGE_DIR                   - Override package directory (for Nix/Guix store paths)\n  PI_OFFLINE                       - Disable startup network operations when set to 1/true/yes\n  PI_SHARE_VIEWER_URL              - Base URL for /share command (default: https://pi.dev/session/)\n  PI_AI_ANTIGRAVITY_VERSION        - Override Antigravity User-Agent version (e.g., 1.23.0)\n\n${chalk.bold(\"Available Tools (default: read, bash, edit, write):\")}\n  read   - Read file contents\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  grep   - Search file contents (read-only, off by default)\n  find   - Find files by glob pattern (read-only, off by default)\n  ls     - List directory contents (read-only, off by default)\n`);\n}\n"]}