fix(import): fall back to body H1 for title when frontmatter lacks title: (#2446)

Title precedence is now frontmatter title: > body's first ATX H1 > the
slug/filename-humanized fallback. Slug-based imports (contacts, calendar)
carry a correct # Heading but no frontmatter title; without the H1 fallback
they got junk titles humanized from the slug. The H1 scan skips h2+ and
lines inside fenced code blocks, and strips closed-ATX trailing hashes.

Takeover of #2495.

Co-authored-by: javieraldape <javieraldape@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/commands/migrate-engine.ts

@@ -3,11 +3,7 @@
  *
  * Usage:
  *   gbrain migrate --to supabase [--url <connection_string>]
- *     (--url is persisted to config.json, mode 0600, so the migrated brain
- *      works without env — #1271)
  *   gbrain migrate --to pglite [--path <db_path>]
- *     (an explicit --path destination is bootstrapped with its own
- *      <path>/.gbrain/config.json so GBRAIN_HOME=<path> just works — #1271)
  *   gbrain migrate --to <engine> --force  (overwrite non-empty target)
  */
 
@@ -15,9 +11,9 @@ import { createEngine } from '../core/engine-factory.ts';
 import { loadConfig, saveConfig, toEngineConfig, gbrainPath, effectiveEnvDatabaseUrl, type GBrainConfig } from '../core/config.ts';
 import type { BrainEngine } from '../core/engine.ts';
 import type { EngineConfig } from '../core/types.ts';
-import { writeFileSync, readFileSync, existsSync, unlinkSync, mkdirSync, chmodSync } from 'fs';
+import { writeFileSync, readFileSync, existsSync, unlinkSync } from 'fs';
 import { createHash } from 'crypto';
-import { resolve, join } from 'path';
+import { resolve } from 'path';
 import { createProgress } from '../core/progress.ts';
 import { getCliOptions, cliOptsToProgressOptions } from '../core/cli-options.ts';
 
@@ -63,31 +59,6 @@ export interface MigrateManifest {
   started_at: string;
 }
 
-/**
- * #1271 Finding 1: make an explicit `--to pglite --path P` destination usable
- * as a standalone brain. Writes `P/.gbrain/config.json` (mode 0600, plus a
- * `*` .gitignore) so `GBRAIN_HOME=P` resolves without a manual `gbrain init`.
- * Never clobbers an existing config at the destination. Returns the written
- * config path, or null when skipped.
- */
-export function bootstrapDestinationConfig(dbPath: string): string | null {
-  const abs = resolve(dbPath);
-  const dir = join(abs, '.gbrain');
-  const file = join(dir, 'config.json');
-  if (existsSync(file)) return null;
-  mkdirSync(dir, { recursive: true });
-  const cfg: GBrainConfig = { engine: 'pglite', database_path: abs };
-  writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
-  try { chmodSync(file, 0o600); } catch { /* platform-specific */ }
-  // Same worktree-safety pattern as saveConfig()'s ensureGitignore, scoped
-  // to the destination home. Don't clobber a user-customized .gitignore.
-  const gitignore = join(dir, '.gitignore');
-  if (!existsSync(gitignore)) {
-    writeFileSync(gitignore, '*\n', { mode: 0o600 });
-  }
-  return file;
-}
-
 export function migrationTargetId(config: EngineConfig): string {
   const locator = config.engine === 'postgres'
     ? config.database_url ?? ''
@@ -381,25 +352,6 @@ export async function runMigrateEngine(sourceEngine: BrainEngine, args: string[]
   };
   saveConfig(newConfig);
 
-  // #1271 Finding 2 (by design, but say it out loud): the connection string
-  // is persisted so the migrated brain works without env. Mode 0600.
-  if (opts.targetEngine === 'postgres' && opts.targetUrl) {
-    console.error('Note: the --url connection string (including credentials) is persisted to config.json (mode 0600).');
-  }
-
-  // #1271 Finding 1: an explicit --path destination doubles as a standalone
-  // GBRAIN_HOME. Best-effort — never fail a completed migration over it.
-  if (opts.targetEngine === 'pglite' && opts.targetPath) {
-    try {
-      const written = bootstrapDestinationConfig(opts.targetPath);
-      if (written) {
-        console.log(`Destination bootstrapped: ${written} (usable via GBRAIN_HOME=${resolve(opts.targetPath)})`);
-      }
-    } catch (e) {
-      console.warn(`  WARN could not bootstrap destination config: ${e instanceof Error ? e.message : String(e)}`);
-    }
-  }
-
   // Clean up
   clearManifest();
 

src/core/markdown.ts

@@ -135,7 +135,16 @@ export function parseMarkdown(
   const type = coerceFrontmatterString(frontmatter.type) || (
     opts?.activePack ? inferTypeFromPack(filePath, opts.activePack) : inferType(filePath)
   );
-  const title = coerceFrontmatterString(frontmatter.title).trim() || inferTitle(filePath);
+  // #2446: title precedence is frontmatter `title:` > the body's first H1 >
+  // the slug/filename-humanized fallback. Slug-based imports (contacts,
+  // calendar) write a correct `# Heading` but no frontmatter title; without
+  // the H1 fallback they get junk titles humanized from the slug
+  // (`Contact 20170928 5 John Defalco`), which also breaks anything keyed on
+  // the title (e.g. the by-mention gazetteer's first-token bucketing).
+  const title =
+    coerceFrontmatterString(frontmatter.title).trim() ||
+    inferTitleFromBody(body) ||
+    inferTitle(filePath);
   const tags = extractTags(frontmatter);
   const slug = coerceFrontmatterString(frontmatter.slug) || inferSlug(filePath);
 
@@ -602,6 +611,31 @@ function inferTypeWithPrefixes(
   return 'concept';
 }
 
+/**
+ * #2446: derive a title from the body's first ATX H1 (`# Heading`).
+ *
+ * Returns the trimmed heading text with the leading `# ` and any decorative
+ * trailing `#` run stripped, or '' if the body has no H1. Only a SINGLE leading
+ * `#` matches — `##`+ (h2 and deeper) are skipped — and lines inside a fenced
+ * code block (```/~~~) are ignored so a `# comment` in a shell snippet can't be
+ * mistaken for the page title.
+ */
+function inferTitleFromBody(body: string): string {
+  let inFence = false;
+  for (const raw of body.split('\n')) {
+    const fence = /^\s*(`{3,}|~{3,})/.exec(raw);
+    if (fence) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    // Exactly one leading `#`, then whitespace, then the heading text.
+    const m = /^#(?!#)\s+(.+?)\s*$/.exec(raw);
+    if (m) return m[1].replace(/\s+#+\s*$/, '').trim();
+  }
+  return '';
+}
+
 function inferTitle(filePath?: string): string {
   if (!filePath) return 'Untitled';
 

test/markdown.test.ts

@@ -343,3 +343,47 @@ describe('issue #1939 — non-string frontmatter coercion', () => {
     expect(parsed.title).toBe('A Normal Title');
   });
 });
+
+// issue #2446 — when frontmatter has no `title:`, prefer the body's first H1
+// over the slug/filename-humanized fallback. Slug-based imports (contacts,
+// calendar) carry a correct `# Heading` but no frontmatter title; humanizing
+// the slug leaks date/id tokens and loses casing (`Defalco` vs `DeFalco`).
+describe('issue #2446 — body H1 fallback for missing frontmatter title', () => {
+  test('no frontmatter title uses the body H1, not the slug-humanized junk', () => {
+    const md = '---\ntype: person\n---\n\n# John DeFalco\n\nNotes about John.\n';
+    const parsed = parseMarkdown(md, 'people/contact-20170928-5-john-defalco.md');
+    expect(parsed.title).toBe('John DeFalco');
+    // The slug-derived junk title must NOT win.
+    expect(parsed.title).not.toBe('Contact 20170928 5 John Defalco');
+  });
+
+  test('no frontmatter title and no H1 falls back to the inferred slug title', () => {
+    const md = '---\ntype: note\n---\n\njust body prose, no heading\n';
+    const parsed = parseMarkdown(md, 'people/alice-example.md');
+    expect(parsed.title).toBe('Alice Example');
+  });
+
+  test('frontmatter title wins over a body H1 (no regression)', () => {
+    const md = '---\ntitle: Frontmatter Wins\n---\n\n# Body Heading\n\nbody\n';
+    const parsed = parseMarkdown(md, 'people/some-slug.md');
+    expect(parsed.title).toBe('Frontmatter Wins');
+  });
+
+  test('h2 is not treated as the title; first real H1 is used', () => {
+    const md = '---\ntype: note\n---\n\n## Subsection First\n\n# The Real Title\n\nbody\n';
+    const parsed = parseMarkdown(md, 'notes/x.md');
+    expect(parsed.title).toBe('The Real Title');
+  });
+
+  test('a # inside a fenced code block is not mistaken for the title', () => {
+    const md = '---\ntype: note\n---\n\n```sh\n# this is a shell comment, not a heading\n```\n\n# Actual Heading\n';
+    const parsed = parseMarkdown(md, 'notes/x.md');
+    expect(parsed.title).toBe('Actual Heading');
+  });
+
+  test('trailing closing hashes are stripped from the H1', () => {
+    const md = '---\ntype: note\n---\n\n# Closed ATX Heading #\n\nbody\n';
+    const parsed = parseMarkdown(md, 'notes/x.md');
+    expect(parsed.title).toBe('Closed ATX Heading');
+  });
+});

test/migrate-engine-dest-bootstrap.test.ts

@@ -1,40 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
-import { tmpdir } from 'os';
-import { join, resolve } from 'path';
-import { bootstrapDestinationConfig } from '../src/commands/migrate-engine.ts';
-import { loadConfigFileOnly } from '../src/core/config.ts';
-import { withEnv } from './helpers/with-env.ts';
-
-describe('migrate --to pglite destination bootstrap (#1271)', () => {
-  test('writes <path>/.gbrain/config.json so GBRAIN_HOME=<path> resolves a brain', async () => {
-    const dest = mkdtempSync(join(tmpdir(), 'gbrain-dest-'));
-    const written = bootstrapDestinationConfig(dest);
-    const file = join(dest, '.gbrain', 'config.json');
-    expect(written).toBe(file);
-
-    const cfg = JSON.parse(readFileSync(file, 'utf-8'));
-    expect(cfg.engine).toBe('pglite');
-    expect(cfg.database_path).toBe(resolve(dest));
-    expect(statSync(file).mode & 0o777).toBe(0o600);
-    // worktree safety: destination home is git-ignored like saveConfig()'s home
-    expect(readFileSync(join(dest, '.gbrain', '.gitignore'), 'utf-8')).toBe('*\n');
-
-    // The exact failure mode from #1271: config resolution under
-    // GBRAIN_HOME=<path> used to find nothing ("No brain configured").
-    await withEnv({ GBRAIN_HOME: dest }, () => {
-      const loaded = loadConfigFileOnly();
-      expect(loaded?.engine).toBe('pglite');
-      expect(loaded?.database_path).toBe(resolve(dest));
-    });
-  });
-
-  test('never clobbers an existing destination config', () => {
-    const dest = mkdtempSync(join(tmpdir(), 'gbrain-dest-'));
-    mkdirSync(join(dest, '.gbrain'), { recursive: true });
-    writeFileSync(join(dest, '.gbrain', 'config.json'), '{"engine":"postgres"}\n');
-
-    expect(bootstrapDestinationConfig(dest)).toBe(null);
-    expect(JSON.parse(readFileSync(join(dest, '.gbrain', 'config.json'), 'utf-8')).engine).toBe('postgres');
-  });
-});