@jossuealcala/madre 0.2.0

package/bin/madre.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { resolve } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { startPulse } from '../src/server.mjs';
+import { detectAgents } from '../src/runtime-detection.mjs';
+import { probeAll } from '../src/auth-probe.mjs';
+import { applyConfigToEnv, loadConfig } from '../src/config.mjs';
+import { isOnline, runSetup } from '../src/setup.mjs';
+import { parseArgs } from '../src/cli-args.mjs';
+
+const cli = parseArgs(process.argv.slice(2));
+const { command } = cli;
+const option = (name, fallback) => cli.option(name.replace(/^--/, ''), fallback);
+const has = (name) => cli.has(name.replace(/^--/, ''));
+
+// With an explicit --port a busy port is an error the user asked for. Without
+// one, MOTHER walks up to the next free port so a second room just opens.
+async function openRoom(options) {
+  const explicit = cli.explicit('port');
+  let port = options.port;
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    try {
+      return await startPulse({ ...options, port });
+    } catch (error) {
+      if (error.code !== 'EADDRINUSE') throw error;
+      if (explicit) {
+        console.error(`\n  MOTHER › port ${port} is already in use. Another MADRE may be open there; try --port ${port + 1} or omit --port to pick one automatically.\n`);
+        process.exit(2);
+      }
+      console.error(`  MOTHER › port ${port} in use, trying ${port + 1}.`);
+      port += 1;
+    }
+  }
+  console.error(`\n  MOTHER › no free port between ${options.port} and ${port}. Pass --port explicitly.\n`);
+  process.exit(2);
+}
+
+const projectRoot = resolve(option('--project', process.cwd()));
+const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
+if (nodeMajor < 22 || (nodeMajor === 22 && nodeMinor < 5)) {
+  console.error(`\n  MOTHER › MADRE needs Node 22.5 or newer (found ${process.version}): the room's memory runs on node:sqlite.\n`);
+  process.exit(2);
+}
+const stateRoot = process.env.PULSE_HOME;
+if (command !== 'help') {
+  const stats = await stat(projectRoot).catch(() => null);
+  if (!stats?.isDirectory()) {
+    console.error(`\n  MOTHER › project folder not found: ${projectRoot}\n  Pass an existing directory with --project, or run MADRE from inside the project.\n`);
+    process.exit(2);
+  }
+}
+applyConfigToEnv(await loadConfig(stateRoot));
+
+if (command === 'doctor' && (has('--catalog') || has('--conditions'))) {
+  // The same knowledge base MU/TH/UR uses in the room, printed for this platform.
+  const { CONDITIONS, fixesFor, searchConditions, PLATFORMS } = await import('../public/troubleshooting.js');
+  const query = option('--catalog', '') || option('--conditions', '') || '';
+  const platform = PLATFORMS[process.platform] ? process.platform : 'linux';
+  const list = query && !query.startsWith('--') ? searchConditions(query) : CONDITIONS;
+  console.log(`\nMU/TH/UR · KNOWN CONDITIONS · ${list.length} OF ${CONDITIONS.length} · ${PLATFORMS[platform].label.toUpperCase()} / ${PLATFORMS[platform].shell.toUpperCase()}\n`);
+  for (const condition of list) {
+    console.log(`▌ ${condition.title}`);
+    console.log(`  ${condition.id} · ${condition.severity}${condition.agent ? ` · @${condition.agent}` : ''}`);
+    console.log(`  ${condition.diagnosis}`);
+    console.log(`  → ${condition.remedy}`);
+    const fixes = fixesFor(condition, platform);
+    if (fixes.length) console.log(fixes.map((line) => `    ${line}`).join('\n'));
+    if (condition.perAgent) for (const [id, byPlatform] of Object.entries(condition.perAgent)) { const lines = byPlatform[platform] ?? byPlatform.darwin ?? []; if (lines.length) console.log(`    # @${id}\n${lines.map((line) => `    ${line}`).join('\n')}`); }
+    console.log('');
+  }
+  process.exitCode = 0;
+} else if (command === 'doctor') {
+  const agents = await detectAgents();
+  const probes = await probeAll(agents);
+  const report = agents.map((agent) => ({ ...agent, session: probes[agent.id] }));
+  const result = {
+    ok: report.some((agent) => isOnline(agent, agent.session)),
+    node: process.version,
+    project: projectRoot,
+    agents: report,
+  };
+
+  if (has('--json')) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log('\nMADRE doctor\n');
+    for (const agent of report) {
+      const mark = agent.ready ? 'ready' : agent.detected ? 'detected' : 'not found';
+      const session = agent.detected ? ` · ${agent.session.state}${agent.session.detail ? ` (${agent.session.detail})` : ''}` : '';
+      console.log(`  ${agent.label.padEnd(10)} ${mark}${agent.version ? ` · ${agent.version}` : ''}${session}`);
+    }
+    console.log(`\n  Project    ${result.project}`);
+    console.log(result.ok ? '\nReady to start. Known conditions and fixes: `madre doctor --catalog [query]`.\n' : '\nNo agent is online. Run `madre setup`. Known conditions and fixes: `madre doctor --catalog`.\n');
+  }
+  process.exitCode = result.ok ? 0 : 1;
+} else if (command === 'setup') {
+  const { action, online } = await runSetup({ projectRoot, stateRoot });
+  if (action === 'start') {
+    await openRoom({ port: Number(option('--port', '4317')), projectRoot, openBrowser: !has('--no-open') });
+  } else {
+    process.exitCode = action === 'report' && !online ? 1 : 0;
+  }
+} else if (command === 'start') {
+  const port = Number(option('--port', '4317'));
+  const noOpen = has('--no-open');
+  // First contact: in a terminal with nobody online, MOTHER walks the user
+  // through configuring an agent before the room opens.
+  if (process.stdin.isTTY && process.stdout.isTTY && !has('--no-setup')) {
+    const agents = await detectAgents();
+    const probes = await probeAll(agents);
+    if (!agents.some((agent) => isOnline(agent, probes[agent.id]))) {
+      const { action } = await runSetup({ projectRoot, stateRoot });
+      if (action !== 'start') process.exit(0);
+    }
+  }
+  await openRoom({ port, projectRoot, openBrowser: !noOpen });
+} else if (command === 'help') {
+  console.log(`MADRE
+
+  madre start [--project PATH] [--port 4317] [--no-open] [--no-setup]
+              Without --port, a busy 4317 falls through to the next free port.
+  madre setup [--project PATH] [--port 4317] [--no-open]
+  madre doctor [--project PATH] [--json]
+
+  start   Opens the project room. With nobody online, runs setup first.
+  setup   Detects the agents on this computer, shows who has a session,
+          and runs each agent's own sign-in from here.
+  doctor  Prints the same diagnosis without the wizard.
+`);
+} else {
+  console.error(`Unknown command: ${command}`);
+  process.exitCode = 1;
+}

package/docs/madre-banner.svg

@@ -0,0 +1,25 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="300" viewBox="0 0 1200 300" role="img" aria-label="MADRE · MU/TH/UR 6000 · INTERFACE 2037">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#050605"/><stop offset="1" stop-color="#0b0d0b"/></linearGradient>
+    <pattern id="scan" width="4" height="4" patternUnits="userSpaceOnUse"><rect width="4" height="1" fill="#9bff66" fill-opacity="0.06"/></pattern>
+    <filter id="glow" x="-20%" y="-50%" width="140%" height="200%"><feGaussianBlur stdDeviation="4" result="b"/><feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge></filter>
+    <filter id="glowSoft" x="-20%" y="-50%" width="140%" height="200%"><feGaussianBlur stdDeviation="10"/></filter>
+  </defs>
+  <rect width="1200" height="300" fill="url(#bg)"/>
+  <rect width="1200" height="300" fill="url(#scan)"/>
+  <rect x="0.5" y="0.5" width="1199" height="299" fill="none" stroke="#9bff66" stroke-opacity="0.18"/>
+  <g transform="translate(90 150)" stroke="#9bff66" fill="none" stroke-width="5" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M0 0 H140 L176 0 L208 -70 L248 70 L284 0 L312 0 L330 -36 L348 0 H460" stroke-opacity="0.25" filter="url(#glowSoft)" stroke-width="14"/>
+    <path d="M0 0 H140 L176 0 L208 -70 L248 70 L284 0 L312 0 L330 -36 L348 0 H460" filter="url(#glow)"/>
+    <circle cx="520" cy="0" r="12" fill="#9bff66" stroke="none" filter="url(#glow)"/>
+  </g>
+  <g font-family="SF Mono, Menlo, Consolas, monospace" fill="#9bff66">
+    <text x="690" y="150" font-size="84" font-weight="700" letter-spacing="14" filter="url(#glow)">MADRE</text>
+    <text x="692" y="194" font-size="15" letter-spacing="6" fill-opacity="0.75">MU/TH/UR 6000 · INTERFACE 2037</text>
+    <text x="692" y="224" font-size="13" letter-spacing="3" fill-opacity="0.55">ONE ROOM · FOUR AGENTS · ONE MEMORY</text>
+  </g>
+  <g font-family="SF Mono, Menlo, Consolas, monospace" font-size="11" letter-spacing="4" fill="#9bff66" fill-opacity="0.45">
+    <text x="90" y="262">CODEX · CLAUDE CODE · GEMINI CLI · OPENCODE</text>
+    <text x="1110" y="262" text-anchor="end">PULSE CHANNEL · LOCAL FIRST</text>
+  </g>
+</svg>

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@jossuealcala/madre",
+  "version": "0.2.0",
+  "description": "MADRE: one local room where the AI coding agents already installed on your machine (Codex, Claude Code, Gemini CLI, OpenCode) work on a project together over the PULSE channel: read-only by default, per-message permission modes up to a checkpointed CONTROL, a shared memory every agent recalls and queries, and NOSTROMO to browse it.",
+  "keywords": [
+    "ai-agents",
+    "codex",
+    "claude-code",
+    "gemini-cli",
+    "opencode",
+    "multi-agent",
+    "local-first",
+    "handoff",
+    "madre",
+    "mother",
+    "mu-th-ur",
+    "memory",
+    "sqlite",
+    "mcp",
+    "pulse"
+  ],
+  "homepage": "https://github.com/jossuealcacao-exe/madre#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jossuealcacao-exe/madre.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jossuealcacao-exe/madre/issues"
+  },
+  "author": {
+    "name": "Jossué Alcalá",
+    "url": "https://jossuealcala.com/en/"
+  },
+  "type": "module",
+  "license": "Apache-2.0",
+  "files": [
+    "bin",
+    "src",
+    "public",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "docs/madre-banner.svg"
+  ],
+  "bin": {
+    "madre": "./bin/madre.mjs",
+    "pulse": "./bin/madre.mjs"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "scripts": {
+    "start": "node ./bin/madre.mjs start",
+    "doctor": "node ./bin/madre.mjs doctor",
+    "test": "node --test",
+    "check": "npm test && node ./bin/madre.mjs doctor --json",
+    "pack:check": "node ./scripts/pack-check.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}