@jaimevalasek/aioson 1.3.0

package/src/i18n/scaffold.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const baseEn = require('./messages/en');
+const { exists, ensureDir } = require('../utils');
+
+function isValidLocaleCode(locale) {
+  return /^[a-z]{2,3}([_-][a-z0-9]{2,8})?$/i.test(locale);
+}
+
+function normalizeLocaleFileName(locale) {
+  return String(locale).trim().toLowerCase().replace(/_/g, '-');
+}
+
+async function createLocaleScaffold(locale, options = {}) {
+  const normalized = normalizeLocaleFileName(locale);
+  const messagesDir = options.messagesDir || path.join(__dirname, 'messages');
+  const force = Boolean(options.force);
+  const dryRun = Boolean(options.dryRun);
+
+  if (!isValidLocaleCode(normalized)) {
+    const error = new Error(`Invalid locale code: ${locale}`);
+    error.code = 'INVALID_LOCALE';
+    throw error;
+  }
+
+  if (normalized === 'en') {
+    const error = new Error('Cannot scaffold locale "en" because it is the base dictionary.');
+    error.code = 'BASE_LOCALE';
+    throw error;
+  }
+
+  await ensureDir(messagesDir);
+  const filePath = path.join(messagesDir, `${normalized}.js`);
+  const alreadyExists = await exists(filePath);
+
+  if (alreadyExists && !force) {
+    const error = new Error(`Locale file already exists: ${filePath}`);
+    error.code = 'LOCALE_EXISTS';
+    error.path = filePath;
+    throw error;
+  }
+
+  const payload = JSON.stringify(baseEn, null, 2);
+  const content = `'use strict';\n\n// TODO: Replace English strings with ${normalized} translations.\nmodule.exports = ${payload};\n`;
+
+  if (!dryRun) {
+    await fs.writeFile(filePath, content, 'utf8');
+  }
+
+  return {
+    locale: normalized,
+    filePath,
+    overwritten: alreadyExists,
+    dryRun
+  };
+}
+
+module.exports = {
+  createLocaleScaffold,
+  isValidLocaleCode,
+  normalizeLocaleFileName
+};

package/src/installer.js

@@ -0,0 +1,232 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { MANAGED_FILES } = require('./constants');
+const { getCliVersion } = require('./version');
+const { exists, ensureDir, copyFileWithDir, nowStamp, toRelativeSafe } = require('./utils');
+const { ensureProjectRuntime } = require('./execution-gateway');
+
+const ROOT_DIR = path.join(__dirname, '..');
+const TEMPLATE_DIR = path.join(ROOT_DIR, 'template');
+const PROJECT_LOCAL_FILES = new Set(['aioson-models.json']);
+const GITIGNORE_POLICY_LINES = [
+  '# AIOSON — keep shared project memory and tool contracts',
+  '!AGENTS.md',
+  '!CLAUDE.md',
+  '!OPENCODE.md',
+  '!.claude/',
+  '!.claude/**',
+  '!.gemini/',
+  '!.gemini/**',
+  '!.aioson/',
+  '!.aioson/**',
+  '# AIOSON — local-only artifacts',
+  'aioson-models.json',
+  '.aioson/backups/',
+  '.aioson/cloud-imports/',
+  '.aioson/runtime/',
+  '.aioson/mcp/presets/',
+  '.aioson/install.json',
+  '.aioson/mcp/servers.local.json'
+];
+
+async function detectExistingInstall(targetDir) {
+  return exists(path.join(targetDir, '.aioson/config.md'));
+}
+
+async function ensureGitignoreEntry(targetDir, entry) {
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  let content = '';
+  if (await exists(gitignorePath)) {
+    content = await fs.readFile(gitignorePath, 'utf8');
+  }
+  if (content.split('\n').some(line => line.trim() === entry)) return false;
+  const separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+  await fs.writeFile(gitignorePath, `${content}${separator}${entry}\n`, 'utf8');
+  return true;
+}
+
+async function ensureGitignoreEntries(targetDir, entries) {
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  let content = '';
+  if (await exists(gitignorePath)) {
+    content = await fs.readFile(gitignorePath, 'utf8');
+  }
+
+  const existing = new Set(content.split('\n').map((line) => line.trim()));
+  const missing = entries.filter((entry) => !existing.has(entry));
+  if (missing.length === 0) return 0;
+
+  const separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+  await fs.writeFile(gitignorePath, `${content}${separator}${missing.join('\n')}\n`, 'utf8');
+  return missing.length;
+}
+
+async function countProjectFiles(targetDir) {
+  const SKIP = new Set(['.git', 'node_modules', 'vendor', '.aioson', 'dist', 'build', '__pycache__']);
+  let count = 0;
+  async function walk(dir) {
+    let entries;
+    try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (SKIP.has(e.name)) continue;
+      if (e.isDirectory()) await walk(path.join(dir, e.name));
+      else count++;
+    }
+  }
+  await walk(targetDir);
+  return count;
+}
+
+async function listFilesRecursive(dir) {
+  const out = [];
+
+  async function walk(current) {
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else {
+        out.push(full);
+      }
+    }
+  }
+
+  await walk(dir);
+  return out;
+}
+
+function shouldSkipTemplatePath(rel) {
+  if (rel.startsWith('.aioson/context/')) return true;
+  if (rel === '.aioson/context/.gitkeep') return false;
+  return false;
+}
+
+async function writeInstallMetadata(targetDir, action, frameworkDetection) {
+  const metaPath = path.join(targetDir, '.aioson/install.json');
+  await ensureDir(path.dirname(metaPath));
+  const existing = (await exists(metaPath)) ? JSON.parse(await fs.readFile(metaPath, 'utf8')) : {};
+
+  const version = await getCliVersion();
+  const data = {
+    ...existing,
+    managed_by: 'aioson',
+    template_version: version,
+    last_action: action,
+    last_action_at: new Date().toISOString(),
+    framework_detected: frameworkDetection || existing.framework_detected || null
+  };
+
+  await fs.writeFile(metaPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+async function backupManagedFile(targetDir, relPath, backupRoot) {
+  const source = path.join(targetDir, relPath);
+  if (!(await exists(source))) return null;
+
+  const dest = path.join(backupRoot, relPath);
+  await copyFileWithDir(source, dest);
+  return dest;
+}
+
+async function installTemplate(targetDir, options = {}) {
+  const {
+    overwrite = false,
+    dryRun = false,
+    mode = 'install',
+    backupOnOverwrite = mode === 'update',
+    frameworkDetection = null
+  } = options;
+
+  await ensureDir(targetDir);
+  const existingInstall = await detectExistingInstall(targetDir);
+
+  const templateFiles = await listFilesRecursive(TEMPLATE_DIR);
+  const copied = [];
+  const skipped = [];
+  const backedUp = [];
+  let runtime = null;
+
+  let backupRoot = null;
+  if (backupOnOverwrite) {
+    backupRoot = path.join(targetDir, '.aioson/backups', nowStamp());
+  }
+
+  for (const absPath of templateFiles) {
+    const rel = toRelativeSafe(TEMPLATE_DIR, absPath);
+    if (shouldSkipTemplatePath(rel)) {
+      skipped.push({ path: rel, reason: 'context-protected' });
+      continue;
+    }
+
+    const dest = path.join(targetDir, rel);
+    const destExists = await exists(dest);
+
+    if (destExists && PROJECT_LOCAL_FILES.has(rel)) {
+      skipped.push({ path: rel, reason: 'project-local' });
+      continue;
+    }
+
+    if (destExists && !overwrite && mode !== 'update') {
+      skipped.push({ path: rel, reason: 'already-exists' });
+      continue;
+    }
+
+    if (destExists && mode === 'update' && backupOnOverwrite && MANAGED_FILES.includes(rel)) {
+      if (!dryRun) {
+        const backupPath = await backupManagedFile(targetDir, rel, backupRoot);
+        if (backupPath) backedUp.push(toRelativeSafe(targetDir, backupPath));
+      } else {
+        backedUp.push(toRelativeSafe(targetDir, path.join(backupRoot, rel)));
+      }
+    }
+
+    if (!dryRun) {
+      await copyFileWithDir(absPath, dest);
+    }
+
+    copied.push(rel);
+  }
+
+  if (!dryRun) {
+    await ensureDir(path.join(targetDir, '.aioson/context/parallel'));
+    await ensureDir(path.join(targetDir, '.aioson/context'));
+    const gitkeep = path.join(targetDir, '.aioson/context/.gitkeep');
+    if (!(await exists(gitkeep))) {
+      await fs.writeFile(gitkeep, '', 'utf8');
+    }
+
+    await writeInstallMetadata(targetDir, mode, frameworkDetection);
+
+    await ensureGitignoreEntries(targetDir, GITIGNORE_POLICY_LINES);
+
+    runtime = await ensureProjectRuntime(targetDir);
+  }
+
+  // Detect if this is an existing project with many files
+  const projectFileCount = await countProjectFiles(targetDir);
+  const isExistingProject = frameworkDetection && projectFileCount > 20;
+
+  return {
+    existingInstall,
+    copied,
+    skipped,
+    backedUp,
+    runtime,
+    dryRun,
+    projectFileCount,
+    isExistingProject
+  };
+}
+
+module.exports = {
+  TEMPLATE_DIR,
+  detectExistingInstall,
+  installTemplate,
+  listFilesRecursive,
+  ensureGitignoreEntry,
+  ensureGitignoreEntries,
+  countProjectFiles
+};

package/src/lib/genomes/compat.js

@@ -0,0 +1,206 @@
+'use strict';
+
+const {
+  parseGenomeMarkdown,
+  serializeGenomeMarkdown
+} = require('../../genome-format');
+const { isGenomeV2, normalizeGenome } = require('../../genomes');
+const { mergeGenomeBindings, normalizeGenomeBindings } = require('../../genomes/bindings');
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasLegacyObjectSignals(input) {
+  return Boolean(
+    input &&
+      (
+        input.genome ||
+        input.slug ||
+        input.domain ||
+        input.title ||
+        input.name ||
+        isObject(input.sections) ||
+        Array.isArray(input.knowledge) ||
+        Array.isArray(input.mentes) ||
+        Array.isArray(input.skills)
+      )
+  );
+}
+
+function buildSectionsFromLegacyObject(input = {}) {
+  if (isObject(input.sections)) {
+    return input.sections;
+  }
+
+  return {
+    knowledge: Array.isArray(input.knowledge) ? input.knowledge : [],
+    philosophies: Array.isArray(input.philosophies) ? input.philosophies : [],
+    mentalModels: Array.isArray(input.mentalModels) ? input.mentalModels : [],
+    heuristics: Array.isArray(input.heuristics) ? input.heuristics : [],
+    frameworks: Array.isArray(input.frameworks) ? input.frameworks : [],
+    methodologies: Array.isArray(input.methodologies) ? input.methodologies : [],
+    mentes: Array.isArray(input.mentes) ? input.mentes : Array.isArray(input.minds) ? input.minds : [],
+    skills: Array.isArray(input.skills) ? input.skills : [],
+    evidence: Array.isArray(input.evidence) ? input.evidence : [],
+    applicationNotes: Array.isArray(input.applicationNotes) ? input.applicationNotes : []
+  };
+}
+
+function hasExplicitModernMarkdownMarkers(input) {
+  const text = String(input || '');
+  return (
+    /\nformat:\s*genome-v[23]\s*$/im.test(text) ||
+    /\nversion:\s*[23]\s*$/im.test(text) ||
+    /\nevidence_mode:\s*.+$/im.test(text) ||
+    /\nsources_count:\s*\d+\s*$/im.test(text) ||
+    /^##\s+(Filosofias|Modelos mentais|Heurísticas|Heuristicas|Frameworks|Metodologias|Perfil Cognitivo|Estilo de Comunicação|Vieses e Pontos Cegos|Evidence|Application notes)\s*$/im.test(text)
+  );
+}
+
+function hasLegacyMarkdownSignals(input) {
+  const text = String(input || '');
+  return (
+    /^\s*---\s*$/m.test(text) ||
+    /\n(?:genome|slug):\s*.+$/im.test(text) ||
+    /^#\s+(Genome|Genoma)\s*:/im.test(text) ||
+    /^##\s+(O que saber|Mentes|Skills)\s*$/im.test(text)
+  );
+}
+
+function toCompatibleGenomeDocument(input, options = {}) {
+  return normalizeGenome({
+    ...(isObject(input) ? input : {}),
+    sections: buildSectionsFromLegacyObject(input),
+    legacyFormat: false,
+    hasFrontmatter: true,
+    sourcePath: options.filePath || null
+  });
+}
+
+function detectGenomeFormat(input) {
+  if (!input) return 'unknown';
+
+  if (typeof input === 'string') {
+    try {
+      if (hasExplicitModernMarkdownMarkers(input)) {
+        const parsed = parseGenomeMarkdown(input);
+        return parsed.version >= 3 || parsed.format === 'genome-v3' ? 'v3-markdown' : 'v2-markdown';
+      }
+      if (hasLegacyMarkdownSignals(input)) return 'legacy-markdown';
+      const genome = parseGenomeMarkdown(input);
+      if (genome.version >= 3 || genome.format === 'genome-v3') return 'v3-markdown';
+      if (isGenomeV2(genome)) return 'v2-markdown';
+      if (genome.legacyFormat) return 'legacy-markdown';
+    } catch {
+      return 'unknown';
+    }
+    return 'unknown';
+  }
+
+  if (isObject(input)) {
+    const normalized = normalizeGenome(input);
+    if (normalized.version >= 3 || normalized.format === 'genome-v3') return 'v3-object';
+    if (isGenomeV2(input)) return 'v2-object';
+    if (hasLegacyObjectSignals(input)) return 'legacy-object';
+  }
+
+  return 'unknown';
+}
+
+function loadCompatibleGenome(input, options = {}) {
+  const format = detectGenomeFormat(input);
+
+  if (format === 'v2-markdown' || format === 'v3-markdown' || format === 'legacy-markdown') {
+    const parsed = parseGenomeMarkdown(input);
+    return {
+      format,
+      document: toCompatibleGenomeDocument(parsed, options),
+      migrated: format === 'legacy-markdown'
+    };
+  }
+
+  if (format === 'v2-object' || format === 'v3-object') {
+    return {
+      format,
+      document: toCompatibleGenomeDocument(input, options),
+      migrated: false
+    };
+  }
+
+  if (format === 'legacy-object') {
+    return {
+      format,
+      document: toCompatibleGenomeDocument(
+        {
+          slug: input.slug || input.genome,
+          domain: input.domain || input.title || input.name || input.slug || input.genome,
+          type: input.type,
+          language: input.language,
+          depth: input.depth,
+          version: input.version,
+          format: input.format,
+          evidenceMode: input.evidenceMode || input.evidence_mode,
+          sourceCount: input.sourceCount ?? input.sourcesCount ?? input.sources_count,
+          generated: input.generated,
+          personaSource: input.personaSource || input.persona_source,
+          personaSources: input.personaSources || input.persona_sources,
+          disc: input.disc,
+          enneagram: input.enneagram,
+          bigFive: input.bigFive || input.big_five,
+          mbti: input.mbti,
+          confidence: input.confidence,
+          profilerReport: input.profilerReport || input.profiler_report,
+          hybridMode: input.hybridMode || input.hybrid_mode,
+          sections: buildSectionsFromLegacyObject(input)
+        },
+        options
+      ),
+      migrated: true
+    };
+  }
+
+  throw new Error('Unsupported genome format.');
+}
+
+function serializeCompatibleGenome(document, options = {}) {
+  return serializeGenomeMarkdown(toCompatibleGenomeDocument(document, options));
+}
+
+function normalizeCompatibleBindings(bindings = {}) {
+  return normalizeGenomeBindings(bindings);
+}
+
+function hasLegacySquadGenomeSignals(manifest = {}) {
+  return Boolean(
+    Array.isArray(manifest.genomes) ||
+      isObject(manifest.genomes) ||
+      isObject(manifest.genomeBindings) ||
+      (Array.isArray(manifest.executors) &&
+        manifest.executors.some((executor) => Array.isArray(executor && executor.genomes) && executor.genomes.length > 0))
+  );
+}
+
+function normalizeLegacySquadGenomes(manifest = {}) {
+  if (!isObject(manifest)) return {};
+  if (!hasLegacySquadGenomeSignals(manifest)) return { ...manifest };
+
+  const genomeBindings = mergeGenomeBindings({
+    blueprintBindings: manifest.genomeBindings,
+    manifestBindings: manifest.genomeBindings || manifest.genomes,
+    legacyExecutors: manifest.executors
+  });
+
+  return {
+    ...manifest,
+    genomeBindings
+  };
+}
+
+module.exports = {
+  detectGenomeFormat,
+  loadCompatibleGenome,
+  serializeCompatibleGenome,
+  normalizeCompatibleBindings,
+  normalizeLegacySquadGenomes
+};

package/src/lib/genomes/migrate.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { loadCompatibleGenome, serializeCompatibleGenome } = require('./compat');
+
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function migrateGenomeFile(filePath, options = {}) {
+  const {
+    dryRun = true,
+    write = false,
+    backup = true,
+    backupDir = null
+  } = options;
+
+  const raw = await fs.readFile(filePath, 'utf8');
+  const loaded = loadCompatibleGenome(raw, { filePath });
+  const output = serializeCompatibleGenome(loaded.document, { filePath });
+  const changed = loaded.migrated;
+
+  const result = {
+    filePath,
+    detectedFormat: loaded.format,
+    migrated: loaded.migrated,
+    changed,
+    output,
+    backupPath: null
+  };
+
+  if (!write || dryRun || !changed) {
+    return result;
+  }
+
+  if (backup) {
+    const targetBackupDir = backupDir || path.join(path.dirname(filePath), '.backup');
+    await ensureDir(targetBackupDir);
+    const backupPath = path.join(targetBackupDir, `${path.basename(filePath)}.bak`);
+    await fs.writeFile(backupPath, raw, 'utf8');
+    result.backupPath = backupPath;
+  }
+
+  await fs.writeFile(filePath, output, 'utf8');
+  return result;
+}
+
+async function migrateGenomeDirectory(dirPath, options = {}) {
+  const entries = await fs.readdir(dirPath, { withFileTypes: true });
+  const results = [];
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name.endsWith('.meta.json')) continue;
+
+    const filePath = path.join(dirPath, entry.name);
+    results.push(await migrateGenomeFile(filePath, options));
+  }
+
+  return {
+    directory: dirPath,
+    total: results.length,
+    changed: results.filter((item) => item.changed).length,
+    results
+  };
+}
+
+async function migrateIfLegacyGenome(filePath, options = {}) {
+  if (!(await fileExists(filePath))) {
+    throw new Error(`Genome file not found: ${filePath}`);
+  }
+  return migrateGenomeFile(filePath, options);
+}
+
+module.exports = {
+  migrateGenomeFile,
+  migrateGenomeDirectory,
+  migrateIfLegacyGenome
+};

package/src/lib/squads/genome-repair.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { normalizeLegacySquadGenomes } = require('../genomes/compat');
+
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function repairSquadManifestGenomeBindings(manifestPath, options = {}) {
+  const {
+    dryRun = true,
+    write = false,
+    backup = true
+  } = options;
+
+  const raw = await fs.readFile(manifestPath, 'utf8');
+  const manifest = JSON.parse(raw);
+  const repaired = normalizeLegacySquadGenomes(manifest);
+  const changed = JSON.stringify(manifest) !== JSON.stringify(repaired);
+
+  const result = {
+    manifestPath,
+    changed,
+    before: manifest,
+    after: repaired,
+    backupPath: null
+  };
+
+  if (!changed || dryRun || !write) {
+    return result;
+  }
+
+  if (backup) {
+    const backupDir = path.join(path.dirname(manifestPath), '.backup');
+    await ensureDir(backupDir);
+    const backupPath = path.join(backupDir, `${path.basename(manifestPath)}.bak`);
+    await fs.writeFile(backupPath, raw, 'utf8');
+    result.backupPath = backupPath;
+  }
+
+  await fs.writeFile(manifestPath, `${JSON.stringify(repaired, null, 2)}\n`, 'utf8');
+  return result;
+}
+
+module.exports = {
+  repairSquadManifestGenomeBindings
+};