hypomnema 1.0.1 → 1.2.0

package/scripts/lib/frontmatter.mjs

@@ -5,7 +5,11 @@ export function parseFrontmatter(content) {
   for (const line of m[1].split(/\r?\n/)) {
     const idx = line.indexOf(':');
     if (idx < 0) continue;
-    fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim().replace(/\s*#.*$/, '').replace(/^["']|["']$/g, '');
+    fm[line.slice(0, idx).trim()] = line
+      .slice(idx + 1)
+      .trim()
+      .replace(/\s*#.*$/, '')
+      .replace(/^["']|["']$/g, '');
   }
   return fm;
 }

package/scripts/lib/hypo-ignore.mjs

@@ -6,19 +6,21 @@ export function loadHypoIgnore(hypoDir) {
   if (!existsSync(ignorePath)) return [];
   return readFileSync(ignorePath, 'utf-8')
     .split('\n')
-    .map(l => l.trim())
-    .filter(l => l && !l.startsWith('#'));
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
 }
 
 function globToRegex(glob) {
-  return new RegExp('^' +
-    glob
-      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-      .replace(/\*\*/g, '\x00')   // placeholder before single-* replacement
-      .replace(/\*/g, '[^/]*')
-      .replace(/\?/g, '[^/]')
-      .replace(/\x00/g, '.*')     // restore ** → .*
-  + '$');
+  return new RegExp(
+    '^' +
+      glob
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, '\x00') // placeholder before single-* replacement
+        .replace(/\*/g, '[^/]*')
+        .replace(/\?/g, '[^/]')
+        .replace(/\x00/g, '.*') + // restore ** → .*
+      '$',
+  );
 }
 
 export function isIgnored(filePath, hypoDir, patterns) {

package/scripts/lib/pkg-json.mjs

@@ -10,7 +10,15 @@
  *   that as a refusal to operate on the destination.
  */
 
-import { existsSync, readFileSync, writeFileSync, renameSync, lstatSync, mkdirSync, unlinkSync } from 'fs';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  lstatSync,
+  mkdirSync,
+  unlinkSync,
+} from 'fs';
 import { join, dirname } from 'path';
 import { createHash } from 'crypto';
 
@@ -20,12 +28,20 @@ export function sha256(buf) {
 
 export function isRegularFile(path) {
   if (!existsSync(path)) return false;
-  try { return lstatSync(path).isFile(); } catch { return false; }
+  try {
+    return lstatSync(path).isFile();
+  } catch {
+    return false;
+  }
 }
 
 export function readFileIfRegular(path) {
   if (!isRegularFile(path)) return null;
-  try { return readFileSync(path); } catch { return null; }
+  try {
+    return readFileSync(path);
+  } catch {
+    return null;
+  }
 }
 
 export function readPkgJson(pkgJsonPath) {
@@ -36,7 +52,7 @@ export function readPkgJson(pkgJsonPath) {
   } catch (err) {
     // Preserve corrupt file as <name>.corrupt-<ts>.json so the user can recover.
     try {
-      const ts  = new Date().toISOString().replace(/[:.]/g, '-');
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const bak = `${pkgJsonPath}.corrupt-${ts}.json`;
       renameSync(pkgJsonPath, bak);
       console.error(`[hypomnema] WARN: ${pkgJsonPath} was not valid JSON. Preserved as ${bak}.`);
@@ -53,7 +69,9 @@ export function writePkgJsonAtomic(pkgJsonPath, data) {
   try {
     renameSync(tmp, pkgJsonPath);
   } catch (err) {
-    try { unlinkSync(tmp); } catch {}
+    try {
+      unlinkSync(tmp);
+    } catch {}
     throw err;
   }
 }

package/scripts/lib/project-create.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * project-create.mjs — atomic auto-project scaffold (fix #23, ADR 0023)
+ *
+ * Invoked by the LLM (NOT a user-facing subcommand — ADR 0023 deprecated
+ * `hypomnema project new`) after the user answers "Y" to a SessionStart /
+ * CwdChanged auto-project offer. One call materializes a whole project:
+ *
+ *   1. mkdir projects/<name>/{decisions,session-log}
+ *   2. copy templates/projects/_template/*.md with token substitution
+ *        <project-name> → name, <started> → date, <working_dir> → cwd,
+ *        YYYY-MM-DD     → today  (frontmatter `updated:` only)
+ *   3. append a row to root hot.md "Active Projects" table
+ *   4. append a `## [today] project-create | <name>` entry to log.md
+ *
+ * Idempotent: existing files/rows/entries are preserved, never overwritten or
+ * duplicated, so a re-run after a partial failure converges.
+ *
+ * CLI:
+ *   node scripts/lib/project-create.mjs --name <slug> --working-dir <path> \
+ *        [--hypo-dir <path>] [--started <YYYY-MM-DD>] [--json]
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join, dirname, resolve, sep } from 'path';
+import { fileURLToPath } from 'url';
+import { resolveHypoRoot, expandHome } from './hypo-root.mjs';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(SCRIPT_DIR, '..', '..');
+const TEMPLATE_DIR = join(PKG_ROOT, 'templates', 'projects', '_template');
+
+const TEMPLATE_FILES = ['index.md', 'prd.md', 'hot.md', 'session-state.md'];
+
+function todayISO() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * Substitute the project tokens in a template file's content.
+ * @param {string} content
+ * @param {{name: string, started: string, workingDir: string, today: string}} vars
+ */
+export function substituteTokens(content, { name, started, workingDir, today }) {
+  return content
+    .split('<project-name>')
+    .join(name)
+    .split('<started>')
+    .join(started)
+    .split('<working_dir>')
+    .join(workingDir)
+    .split('YYYY-MM-DD')
+    .join(today);
+}
+
+/**
+ * Insert a project row into the root hot.md "Active Projects" table.
+ * Idempotent: returns the original content unchanged if a row already links
+ * to `[[projects/<name>/hot]]`. Returns null if the table cannot be located.
+ * @returns {string|null} new content, or null when no table marker is found
+ */
+export function insertHotRow(content, name, today) {
+  const link = `[[projects/${name}/hot]]`;
+  if (content.includes(link)) return content; // already present
+  const lines = content.split('\n');
+  // Scope the search to the "## Active Projects" section so a table appearing
+  // earlier in hot.md can't capture the row (codex review 2026-05-22). Start
+  // looking from the heading; stop at the next H2 so we never cross sections.
+  const headingIdx = lines.findIndex((l) => /^##\s+Active Projects\s*$/.test(l));
+  if (headingIdx === -1) return null;
+  let sepIdx = -1;
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    if (/^##\s/.test(lines[i])) break; // next section — table not found in scope
+    if (/^\|\s*-{2,}\s*\|/.test(lines[i])) {
+      sepIdx = i;
+      break;
+    }
+  }
+  if (sepIdx === -1) return null;
+  const row = `| ${name} | ${today} | ${link} |`;
+  lines.splice(sepIdx + 1, 0, row);
+  return lines.join('\n');
+}
+
+/**
+ * Create a project. Idempotent and best-effort per side effect: a missing root
+ * hot.md / log.md is reported in `warnings` rather than thrown, so the core
+ * project files still land.
+ *
+ * @param {{hypoDir: string, name: string, workingDir: string, started?: string, today?: string}} opts
+ * @returns {{created: string[], skipped: string[], warnings: string[], projectDir: string}}
+ */
+export function createProject(opts) {
+  const { name, workingDir } = opts;
+  // Name must be a single path segment with at least one alnum. The charset
+  // alone is not enough: `.`, `..`, `...` all pass `[A-Za-z0-9._-]+` yet would
+  // resolve `projects/<name>` to the wiki root or `projects/` itself (codex
+  // review 2026-05-22, both workers). Reject dot-only names and require alnum.
+  if (!name || !/^[A-Za-z0-9._-]+$/.test(name) || /^\.+$/.test(name) || !/[A-Za-z0-9]/.test(name)) {
+    throw new Error(
+      `invalid project name: ${JSON.stringify(name)} (need a single segment with ≥1 alnum, charset A-Za-z0-9._-, not "."/"..")`,
+    );
+  }
+  if (!workingDir) throw new Error('workingDir is required');
+
+  const hypoDir = opts.hypoDir || resolveHypoRoot();
+  const today = opts.today || todayISO();
+  const started = opts.started || today;
+  const vars = { name, started, workingDir, today };
+
+  const created = [];
+  const skipped = [];
+  const warnings = [];
+
+  const projectsRoot = resolve(hypoDir, 'projects');
+  const projectDir = join(projectsRoot, name);
+  // Defense in depth: the resolved target must stay strictly inside projects/.
+  if (
+    resolve(projectDir) !== join(projectsRoot, name) ||
+    !resolve(projectDir).startsWith(projectsRoot + sep)
+  ) {
+    throw new Error(`project name escapes projects/: ${JSON.stringify(name)}`);
+  }
+  for (const sub of ['decisions', 'session-log']) {
+    mkdirSync(join(projectDir, sub), { recursive: true });
+  }
+
+  for (const file of TEMPLATE_FILES) {
+    const src = join(TEMPLATE_DIR, file);
+    const dest = join(projectDir, file);
+    if (!existsSync(src)) {
+      warnings.push(`template missing: ${file}`);
+      continue;
+    }
+    if (existsSync(dest)) {
+      skipped.push(`projects/${name}/${file}`);
+      continue;
+    }
+    writeFileSync(dest, substituteTokens(readFileSync(src, 'utf-8'), vars));
+    created.push(`projects/${name}/${file}`);
+  }
+
+  // root hot.md pointer row
+  const hotPath = join(hypoDir, 'hot.md');
+  if (existsSync(hotPath)) {
+    const orig = readFileSync(hotPath, 'utf-8');
+    const next = insertHotRow(orig, name, today);
+    if (next === null) {
+      warnings.push('root hot.md: no Active Projects table found — add row manually');
+    } else if (next !== orig) {
+      writeFileSync(hotPath, next);
+      created.push('hot.md row');
+    } else {
+      skipped.push('hot.md row');
+    }
+  } else {
+    warnings.push('root hot.md missing — skipped pointer row');
+  }
+
+  // log.md entry
+  const logPath = join(hypoDir, 'log.md');
+  const entry = `## [${today}] project-create | ${name}`;
+  if (existsSync(logPath)) {
+    const log = readFileSync(logPath, 'utf-8');
+    if (log.includes(entry)) {
+      skipped.push('log.md entry');
+    } else {
+      writeFileSync(logPath, log.replace(/\s*$/, '\n') + `\n${entry}\n`);
+      created.push('log.md entry');
+    }
+  } else {
+    warnings.push('log.md missing — skipped activity entry');
+  }
+
+  return { created, skipped, warnings, projectDir };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = { json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') args.json = true;
+    else if (a === '--name') args.name = argv[++i];
+    else if (a === '--working-dir') args.workingDir = expandHome(argv[++i]);
+    else if (a === '--hypo-dir') args.hypoDir = expandHome(argv[++i]);
+    else if (a === '--started') args.started = argv[++i];
+    else if (a === '--help' || a === '-h') args.help = true;
+  }
+  return args;
+}
+
+const USAGE = `Usage: project-create.mjs --name <slug> --working-dir <path> [--hypo-dir <path>] [--started YYYY-MM-DD] [--json]`;
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (!args.name || !args.workingDir) {
+    console.error(`Error: --name and --working-dir are required\n${USAGE}`);
+    process.exit(1);
+  }
+  let result;
+  try {
+    result = createProject(args);
+  } catch (err) {
+    console.error(`Error: ${err?.message ?? String(err)}`);
+    process.exit(1);
+  }
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    result.created.forEach((c) => console.log(`✓ created ${c}`));
+    result.skipped.forEach((s) => console.log(`· skipped ${s} (exists)`));
+    result.warnings.forEach((w) => console.warn(`⚠ ${w}`));
+    console.log(`\nProject '${args.name}' ready at ${result.projectDir}`);
+  }
+}
+
+// Run as CLI only when invoked directly, not when imported by tests.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main();
+}

package/scripts/lib/schema-vocab.mjs

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const VOCAB_HEADER_RE = /^##\s+(?:\d+\.\s+)?Tag\s+(?:Vocabulary|Taxonomy)\s*$/m;
+const TYPE_TAXONOMY_HEADER_RE = /^##\s+(?:\d+\.\s+)?Page\s+Type\s+Taxonomy\s*$/m;
+const PAGE_DIR_TOKEN_RE = /`pages\/([a-z0-9-]+)\//g;
+const NEXT_H2_RE = /^##\s+/m;
+const CATEGORY_PREFIX_RE = /^\s*\*\*[^*]+\*\*:\s*/;
+const BACKTICK_TOKEN_RE = /`([^`]+)`/g;
+
+const FORBIDDEN_PATTERNS = [
+  { name: 'PascalCase', test: (t) => /[A-Z]/.test(t) },
+  { name: 'whitespace', test: (t) => /\s/.test(t) },
+  {
+    name: 'generic',
+    test: (t) => ['general', 'misc', 'other', 'todo'].includes(t),
+  },
+  {
+    name: 'plural',
+    test: (t) => ['learnings', 'tips', 'feedbacks', 'concepts', 'playbooks'].includes(t),
+  },
+];
+
+export function checkForbidden(tag) {
+  for (const rule of FORBIDDEN_PATTERNS) {
+    if (rule.test(tag)) return rule.name;
+  }
+  return null;
+}
+
+// Extract only backtick tokens from canonical vocabulary lines.
+// A vocabulary line is one whose non-backtick residue (after stripping an
+// optional `**Category**:` prefix) contains only separators (whitespace, commas).
+// This excludes prose like "...`lint` blocks unknown tags..." and table rows
+// in the Forbidden patterns section that mention example tokens.
+function vocabLineTokens(rawLine) {
+  const line = rawLine.replace(CATEGORY_PREFIX_RE, '').trim();
+  if (!line) return [];
+  const residue = line.replace(/`[^`]+`/g, '').trim();
+  if (!/^[\s,]*$/.test(residue)) return [];
+  const tokens = [];
+  for (const m of line.matchAll(BACKTICK_TOKEN_RE)) {
+    const t = m[1].trim();
+    if (t && !t.includes(' ')) tokens.push(t);
+  }
+  return tokens;
+}
+
+export function parseSchemaVocab(hypoDir) {
+  const path = join(hypoDir, 'SCHEMA.md');
+  if (!existsSync(path)) return new Set();
+  const content = readFileSync(path, 'utf-8');
+
+  const headerMatch = VOCAB_HEADER_RE.exec(content);
+  if (!headerMatch) return new Set();
+
+  const sectionStart = headerMatch.index + headerMatch[0].length;
+  const rest = content.slice(sectionStart);
+  const nextH2 = NEXT_H2_RE.exec(rest);
+  const section = nextH2 ? rest.slice(0, nextH2.index) : rest;
+
+  const vocab = new Set();
+  for (const rawLine of section.split('\n')) {
+    for (const token of vocabLineTokens(rawLine)) vocab.add(token);
+  }
+  return vocab;
+}
+
+// Derive the set of valid immediate subdirectories under pages/ from the
+// SCHEMA "Page Type Taxonomy" table (e.g. learnings, feedback, people). Single
+// source of truth — adding a type+dir row to SCHEMA automatically widens the
+// whitelist. Returns an empty Set when SCHEMA.md or the table is absent, which
+// callers treat as "skip the check" for back-compat with minimal wikis.
+export function parseSchemaPageDirs(hypoDir) {
+  const path = join(hypoDir, 'SCHEMA.md');
+  if (!existsSync(path)) return new Set();
+  const content = readFileSync(path, 'utf-8');
+
+  const headerMatch = TYPE_TAXONOMY_HEADER_RE.exec(content);
+  if (!headerMatch) return new Set();
+
+  const sectionStart = headerMatch.index + headerMatch[0].length;
+  const rest = content.slice(sectionStart);
+  const nextH2 = NEXT_H2_RE.exec(rest);
+  const section = nextH2 ? rest.slice(0, nextH2.index) : rest;
+
+  // Only scan table rows (lines starting with `|`) so a backticked path that
+  // appears in surrounding prose (e.g. an example of a *wrong* dir) can never
+  // leak into the whitelist.
+  const dirs = new Set();
+  for (const rawLine of section.split('\n')) {
+    if (!rawLine.trimStart().startsWith('|')) continue;
+    for (const m of rawLine.matchAll(PAGE_DIR_TOKEN_RE)) dirs.add(m[1]);
+  }
+  return dirs;
+}