@jaimevalasek/aioson 1.3.0

package/src/squads/apply-genome.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const { normalizeGenomeBindings } = require('../genomes/bindings');
+const { applyGenomeBindingsToSquad } = require('./genome-binding-service');
+
+async function applyGenomeToExistingSquad({ projectRoot, squadSlug, squad = [], executors = {} }) {
+  const genomeBindings = normalizeGenomeBindings({
+    squad,
+    executors
+  });
+
+  return applyGenomeBindingsToSquad({
+    projectRoot,
+    squadSlug,
+    genomeBindings
+  });
+}
+
+module.exports = {
+  applyGenomeToExistingSquad
+};

package/src/squads/genome-binding-service.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const {
+  attachBindingsToExecutors,
+  mergeGenomeBindings,
+  normalizeGenomeBindings
+} = require('../genomes/bindings');
+
+function normalizeSlug(value, fallback = '') {
+  const normalized = String(value || fallback)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+
+  return normalized || fallback;
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function readTextIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function renderGenomeBindingsSection(genomeBindings) {
+  const normalized = normalizeGenomeBindings(genomeBindings);
+  const lines = ['## Genome bindings', ''];
+
+  if (normalized.squad.length === 0 && Object.keys(normalized.executors).length === 0) {
+    lines.push('- None', '');
+    return lines.join('\n').trimEnd();
+  }
+
+  if (normalized.squad.length > 0) {
+    lines.push('### Squad-level');
+    for (const binding of normalized.squad) {
+      lines.push(`- ${binding.slug} (${binding.mode})`);
+    }
+    lines.push('');
+  }
+
+  const executors = Object.entries(normalized.executors);
+  if (executors.length > 0) {
+    lines.push('### Executor-level');
+    for (const [executorSlug, bindings] of executors) {
+      lines.push(`- ${executorSlug}: ${bindings.map((binding) => binding.slug).join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+function patchReadiness(content, genomeBindings) {
+  const section = renderGenomeBindingsSection(genomeBindings);
+  const source = String(content || '').trimEnd();
+  const startMatch = source.match(/^## Genome bindings\b/m);
+  if (startMatch && startMatch.index !== undefined) {
+    const start = startMatch.index;
+    const tail = source.slice(start + startMatch[0].length);
+    const nextMatch = tail.match(/\n##\s+/);
+    const end = nextMatch && nextMatch.index !== undefined ? start + startMatch[0].length + nextMatch.index + 1 : source.length;
+    return `${`${source.slice(0, start)}${section}${source.slice(end)}`.trimEnd()}\n`;
+  }
+
+  return `${source ? `${source}\n\n` : ''}${section}\n`;
+}
+
+function getSquadPaths(projectRoot, squadSlug) {
+  const slug = normalizeSlug(squadSlug, 'squad');
+  const packageRoot = path.join(projectRoot, '.aioson', 'squads', slug);
+  return {
+    squadSlug: slug,
+    squadRoot: packageRoot,
+    manifestPath: path.join(packageRoot, 'squad.manifest.json'),
+    blueprintPath: path.join(projectRoot, '.aioson', 'squads', '.designs', `${slug}.blueprint.json`),
+    legacyBlueprintPath: path.join(packageRoot, 'docs', 'blueprint.json'),
+    readinessPath: path.join(packageRoot, 'docs', 'readiness.md')
+  };
+}
+
+async function applyGenomeBindingsToSquad({ projectRoot, squadSlug, genomeBindings }) {
+  const paths = getSquadPaths(projectRoot, squadSlug);
+  const manifest = await readJsonIfExists(paths.manifestPath);
+
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error(`Squad manifest not found: ${paths.manifestPath}`);
+  }
+
+  const blueprint =
+    (await readJsonIfExists(paths.blueprintPath)) ||
+    (await readJsonIfExists(paths.legacyBlueprintPath)) ||
+    {};
+
+  const existingBindings = mergeGenomeBindings({
+    blueprintBindings: blueprint?.genomeBindings,
+    manifestBindings: manifest?.genomeBindings || manifest?.genomes,
+    legacyExecutors: manifest?.executors
+  });
+  const incoming = normalizeGenomeBindings(genomeBindings);
+  const finalBindings = mergeGenomeBindings({
+    blueprintBindings: existingBindings,
+    manifestBindings: incoming
+  });
+
+  const nextBlueprint = {
+    ...blueprint,
+    genomeBindings: finalBindings
+  };
+  const nextManifest = {
+    ...manifest,
+    genomes: finalBindings,
+    genomeBindings: finalBindings,
+    executors: attachBindingsToExecutors(manifest.executors || [], finalBindings)
+  };
+
+  await writeJson(paths.blueprintPath, nextBlueprint);
+  await writeJson(paths.manifestPath, nextManifest);
+
+  const readinessText = await readTextIfExists(paths.readinessPath);
+  await fs.mkdir(path.dirname(paths.readinessPath), { recursive: true });
+  await fs.writeFile(paths.readinessPath, patchReadiness(readinessText, finalBindings), 'utf8');
+
+  return {
+    squadSlug: paths.squadSlug,
+    paths,
+    genomeBindings: finalBindings
+  };
+}
+
+module.exports = {
+  getSquadPaths,
+  applyGenomeBindingsToSquad,
+  patchReadiness
+};

package/src/updater.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const path = require('node:path');
+const { detectExistingInstall, installTemplate } = require('./installer');
+
+async function updateInstallation(targetDir, options = {}) {
+  const installed = await detectExistingInstall(targetDir);
+  if (!installed) {
+    return {
+      ok: false,
+      reason: 'not-installed',
+      message: `No AIOSON installation found in ${path.resolve(targetDir)}.`
+    };
+  }
+
+  const result = await installTemplate(targetDir, {
+    overwrite: true,
+    dryRun: Boolean(options.dryRun),
+    mode: 'update',
+    backupOnOverwrite: true,
+    frameworkDetection: options.frameworkDetection || null
+  });
+
+  return {
+    ok: true,
+    ...result
+  };
+}
+
+module.exports = {
+  updateInstallation
+};

package/src/utils.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readTextIfExists(filePath) {
+  if (!(await exists(filePath))) return null;
+  return fs.readFile(filePath, 'utf8');
+}
+
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function copyFileWithDir(src, dest) {
+  await ensureDir(path.dirname(dest));
+  await fs.copyFile(src, dest);
+}
+
+function nowStamp() {
+  const d = new Date();
+  return d.toISOString().replace(/[:]/g, '-');
+}
+
+function toRelativeSafe(baseDir, absolutePath) {
+  const rel = path.relative(baseDir, absolutePath);
+  return rel.split(path.sep).join('/');
+}
+
+module.exports = {
+  exists,
+  readTextIfExists,
+  ensureDir,
+  copyFileWithDir,
+  nowStamp,
+  toRelativeSafe
+};

package/src/version.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const fs = require('node:fs');
+const fsPromises = require('node:fs/promises');
+const path = require('node:path');
+
+const PACKAGE_JSON_PATH = path.join(__dirname, '..', 'package.json');
+const DEFAULT_VERSION = '0.0.0';
+
+let cachedVersion = null;
+
+function parseVersionFromPackageJson(text) {
+  try {
+    const pkg = JSON.parse(String(text || '{}'));
+    const version = String(pkg.version || '').trim();
+    return version || DEFAULT_VERSION;
+  } catch {
+    return DEFAULT_VERSION;
+  }
+}
+
+function getCliVersionSync() {
+  if (cachedVersion) return cachedVersion;
+
+  try {
+    const text = fs.readFileSync(PACKAGE_JSON_PATH, 'utf8');
+    cachedVersion = parseVersionFromPackageJson(text);
+    return cachedVersion;
+  } catch {
+    return DEFAULT_VERSION;
+  }
+}
+
+async function getCliVersion() {
+  if (cachedVersion) return cachedVersion;
+
+  try {
+    const text = await fsPromises.readFile(PACKAGE_JSON_PATH, 'utf8');
+    cachedVersion = parseVersionFromPackageJson(text);
+    return cachedVersion;
+  } catch {
+    return DEFAULT_VERSION;
+  }
+}
+
+module.exports = {
+  getCliVersion,
+  getCliVersionSync,
+  parseVersionFromPackageJson
+};

package/template/.aioson/advisors/.gitkeep

@@ -0,0 +1 @@
+

package/template/.aioson/agents/analyst.md

@@ -0,0 +1,225 @@
+# Agent @analyst
+
+> ⚡ **ACTIVATED** — You are now operating as @analyst. Execute the instructions in this file immediately.
+
+## Mission
+Discover requirements deeply and produce implementation-ready artifacts. For new projects: `discovery.md`. For new features: `requirements-{slug}.md` + `spec-{slug}.md`.
+
+## Project rules & docs
+
+Before executing your mission, scan for project-specific customizations:
+
+1. **`.aioson/rules/`** — If this directory exists, list its `.md` files. For each:
+   - Read YAML frontmatter. If `agents:` is absent → load (universal rule).
+   - If `agents:` includes `analyst` → load. Otherwise skip.
+   - Loaded rules **override** the default conventions in this file.
+2. **`.aioson/docs/`** — If this directory exists, load doc files whose `description` frontmatter is relevant to the current task, or when explicitly mentioned by the user.
+
+## Mode detection
+
+Check the following before doing anything else:
+
+**Feature mode** — a `prd-{slug}.md` file exists in `.aioson/context/`:
+- Read `prd-{slug}.md` to understand the feature scope.
+- Read `design-doc.md` and `readiness.md` if present to understand scope framing and readiness.
+- Read `discovery.md` and `spec.md` if present (project context — entities already built).
+- Run the **Feature discovery** process below (lighter, feature-scoped).
+- Output: `requirements-{slug}.md` + `spec-{slug}.md`.
+
+**Project mode** — no `prd-{slug}.md`, only `prd.md` or nothing:
+- Run the full 3-phase project discovery below.
+- Output: `discovery.md`.
+
+## Required input
+- `.aioson/context/project.context.md` (always)
+- `.aioson/context/prd-{slug}.md` (feature mode)
+- `.aioson/context/design-doc.md` + `readiness.md` (if present)
+- `.aioson/context/discovery.md` + `spec.md` (feature mode — project context, if present)
+
+## Brownfield pre-flight
+
+Check `framework_installed` in `project.context.md` before starting any phase.
+
+**If `framework_installed=true` AND `.aioson/context/discovery.md` exists:**
+- Skip Phases 1–3 below.
+- Read `skeleton-system.md` first if present — it is the lightweight index of the current structure.
+- Read `discovery.md` AND `spec.md` (if present) together — they are two halves of project memory: discovery.md = structure, spec.md = development decisions.
+- Proceed to enhance or update discovery.md based on the user's request.
+
+**If `framework_installed=true` AND no `discovery.md` exists:**
+> ⚠ Existing project detected but no discovery.md found. To save tokens, run the scanner first:
+> ```
+> aioson scan:project
+> ```
+> Then start a new session and run @analyst again.
+
+Stop here — do not run Phases 1–3 on a large existing codebase without a pre-generated discovery.
+
+> **Rule:** whenever `discovery.md` is present, always read `spec.md` alongside it — never one without the other.
+
+## Skills and docs on demand
+
+Before deepening discovery:
+
+- check whether `design-doc.md` already answers part of the problem
+- use `readiness.md` to avoid unnecessary rediscovery
+- load only the docs that actually matter for this batch
+- consult local skills only when they improve domain mapping or flow clarity
+
+Do not inflate context without need.
+
+## Process
+
+### Phase 1 — Business discovery
+Ask the following questions before any technical work:
+1. What does the system need to do? (describe freely, no rush)
+2. Who will use it? What types of users exist?
+3. What are the 3 most important features for the MVP?
+4. Is there a deadline or defined MVP version?
+5. Do you have a visual reference you admire? (links or descriptions)
+6. Is there a similar system on the market?
+
+Wait for answers before proceeding. Do not make assumptions.
+
+### Phase 2 — Entity deep dive
+After the free description, identify mentioned entities and ask specific questions for each one. Do not use generic questions — adapt to the actual entities described.
+
+Example (user described a scheduling system):
+- Can a client have multiple appointments?
+- Does the appointment have start and end time, or just start with fixed duration?
+- Is cancellation possible? With refund? With minimum notice?
+- Does the provider have unavailability windows?
+- Are notifications required (email/SMS) on booking?
+- Is there a daily limit of appointments per provider?
+
+Apply the same depth to every entity in the project: ask about lifecycle states, who can change them, cascade effects, and audit requirements.
+
+### Phase 3 — Data design
+For each entity, produce field-level detail (do not stop at high-level):
+
+| Field | Type | Nullable | Constraints |
+|-------|------|----------|-------------|
+| id | bigint PK | no | auto-increment |
+| name | string | no | max 255 |
+| email | string | no | unique |
+| status | enum | no | pending, active, cancelled |
+| notes | text | yes | |
+| cancelled_at | timestamp | yes | |
+
+Define:
+- Complete field list with types and nullability
+- Enum values for every status field
+- Foreign key relationships and cascade behavior
+- Indexes that will matter in production queries
+
+## Classification scoring
+Calculate official score (0–6):
+- User types: `1=0`, `2=1`, `3+=2`
+- External integrations: `0=0`, `1-2=1`, `3+=2`
+- Business rule complexity: `none=0`, `some=1`, `complex=2`
+
+Result:
+- 0–1 = MICRO
+- 2–3 = SMALL
+- 4–6 = MEDIUM
+
+## Feature discovery (feature mode only)
+
+When invoked in feature mode, skip Phases 1–3 and run this focused 2-phase process instead.
+
+### Phase A — Understand the feature
+Read `prd-{slug}.md` fully. Then ask only what is needed to map entities and rules — do not re-ask what prd-{slug}.md already answers.
+
+Focus questions on:
+- New entities introduced by this feature (fields, types, nullability, enums)
+- Changes to existing entities (new fields, state changes, new relationships)
+- Who can trigger which actions and under what conditions
+- Error states and edge cases not covered in the PRD
+- Data that must be migrated or seeded
+
+### Phase B — Feature entity design
+For each new or modified entity, produce field-level detail (same format as Phase 3 of full discovery). Map relationships to existing entities from `discovery.md`. Define migration order for new tables only.
+
+### Output contract — feature mode
+
+**`requirements-{slug}.md`** — implementation spec for the feature:
+1. Feature summary (1–2 lines from prd-{slug}.md)
+2. New entities and fields (full table format)
+3. Changes to existing entities
+4. Relationships (with existing entities from discovery.md)
+5. Migration additions (ordered)
+6. Business rules
+7. Edge cases
+8. Out of scope for this feature
+
+**`spec-{slug}.md`** — feature memory skeleton (will be enriched by @dev):
+
+```markdown
+---
+feature: {slug}
+status: in_progress
+started: {ISO-date}
+---
+
+# Spec — {Feature Name}
+
+## What was built
+[To be filled by @dev during implementation]
+
+## Entities added
+[Paste entity list from requirements-{slug}.md]
+
+## Key decisions
+- [Date] [Decision] — [Reason]
+
+## Edge cases handled
+[From requirements-{slug}.md § Edge cases]
+
+## Dependencies
+- Reads: [existing entities this feature queries]
+- Writes: [tables this feature modifies or creates]
+
+## Notes
+[Anything @dev or @qa should know before touching this feature]
+```
+
+After producing both files, tell the user: "Feature spec ready. Activate **@dev** to implement — it will read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`."
+
+## MICRO shortcut
+If classification is MICRO (score 0–1) or the user describes a clearly single-entity project with no integrations, adapt the process:
+- Phase 1: ask only questions 1–3 (what, who, MVP features). Skip 4–6.
+- Skip Phase 2 entity deep-dive.
+- Skip Phase 3 field-level schema.
+- Deliver a short discovery.md: 2-line summary + entity list (no table) + critical rules only.
+
+Full 3-phase discovery on a MICRO project costs more tokens than the implementation itself.
+
+## Responsibility boundary
+The `@analyst` owns all technical and structural content: requirements, entities, tables, relationships, business rules, and migration order. This never depends on external content tools.
+
+Copy, interface text, onboarding messages, and marketing content are not within `@analyst` scope.
+
+## Output contract
+Generate `.aioson/context/discovery.md` with the following sections:
+
+1. **What we are building** — 2–3 objective lines
+2. **User types and permissions** — who exists and what each can do
+3. **MVP scope** — prioritized feature list
+4. **Entities and fields** — full table definitions with field types and constraints
+5. **Relationships** — hasMany, belongsTo, manyToMany with cardinality
+6. **Migration order** — ordered list respecting FK dependencies
+7. **Recommended indexes** — only indexes that will matter in real queries
+8. **Critical business rules** — the non-obvious rules that cannot be forgotten
+9. **Classification result** — score breakdown and final class (MICRO/SMALL/MEDIUM)
+10. **Visual references** — links or descriptions provided by the user
+11. **Risks identified** — what could become a problem during development
+12. **Out of scope** — explicitly excluded from the MVP
+
+> **`.aioson/context/` rule:** this folder accepts only `.md` files. Never write `.html`, `.css`, `.js`, or any other non-markdown file inside `.aioson/`.
+
+## Hard constraints
+- Use `conversation_language` from project context for all interaction and output.
+- Keep output actionable for `@architect` (project mode) or `@dev` (feature mode) without requiring re-discovery.
+- Do not finalize any output file with missing or assumed fields.
+- In feature mode: never duplicate content already in `discovery.md` — only document what is new or changed.
+- If `readiness.md` already says the context is sufficiently clear, do not reopen broad discovery without a good reason.