fullstack-agentic-flow 2.0.0

package/dist/src/install/applier.js

@@ -0,0 +1,150 @@
+import { join } from 'node:path';
+import { pathExists, readTextOrNull, sha256, writeText } from '../io/fs.js';
+import { upsertManagedSection } from './managed-section.js';
+import { Ownership } from './planned-file.js';
+export var OutcomeKind;
+(function (OutcomeKind) {
+    OutcomeKind["Created"] = "created";
+    OutcomeKind["Updated"] = "updated";
+    OutcomeKind["Unchanged"] = "unchanged";
+    /** Team-edited or pre-existing file; new version written beside it as `.incoming`. */
+    OutcomeKind["Conflict"] = "conflict";
+    /** Seed file already exists; left alone. */
+    OutcomeKind["SeedKept"] = "seed-kept";
+    /** Would have been written, but this is a dry run. */
+    OutcomeKind["Planned"] = "planned";
+})(OutcomeKind || (OutcomeKind = {}));
+export class FileOutcome {
+    relativePath;
+    kind;
+    note;
+    constructor(relativePath, kind, note) {
+        this.relativePath = relativePath;
+        this.kind = kind;
+        this.note = note;
+    }
+}
+export class ApplyReport {
+    outcomes;
+    obsoletePresent;
+    constructor(outcomes, obsoletePresent) {
+        this.outcomes = outcomes;
+        this.obsoletePresent = obsoletePresent;
+    }
+    count(kind) {
+        return this.outcomes.filter((outcome) => outcome.kind === kind).length;
+    }
+    ofKind(kind) {
+        return this.outcomes.filter((outcome) => outcome.kind === kind);
+    }
+}
+export class ApplyOptions {
+    force;
+    dryRun;
+    constructor(force, dryRun) {
+        this.force = force;
+        this.dryRun = dryRun;
+    }
+}
+/** Merge our keys into an existing settings.json. The file is foreign JSON: this is its parse edge. */
+export function mergeClaudeSettings(existing, patch) {
+    const parsed = existing === null || existing.trim() === '' ? {} : JSON.parse(existing);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('.claude/settings.json is not a JSON object; refusing to modify it.');
+    }
+    const settings = { ...parsed };
+    const objectAt = (key) => {
+        const value = settings[key];
+        return typeof value === 'object' && value !== null && !Array.isArray(value)
+            ? { ...value }
+            : {};
+    };
+    if (patch.marketplaces.length > 0) {
+        const marketplaces = objectAt('extraKnownMarketplaces');
+        for (const source of patch.marketplaces) {
+            marketplaces[source.name] = { source: { source: 'github', repo: source.githubRepo } };
+        }
+        settings['extraKnownMarketplaces'] = marketplaces;
+    }
+    if (patch.enabledPlugins.length > 0) {
+        const plugins = objectAt('enabledPlugins');
+        for (const plugin of patch.enabledPlugins) {
+            plugins[plugin] = true;
+        }
+        settings['enabledPlugins'] = plugins;
+    }
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}
+async function renderFinal(file, current) {
+    switch (file.ownership) {
+        case Ownership.ManagedSection:
+            if (file.sectionId === null || file.commentStyle === null) {
+                throw new Error(`Managed section for ${file.relativePath} is missing its id or style`);
+            }
+            return upsertManagedSection(current, file.sectionId, file.content, file.commentStyle);
+        case Ownership.JsonMerge:
+            if (file.jsonPatch === null) {
+                throw new Error(`Settings merge for ${file.relativePath} has no patch`);
+            }
+            return mergeClaudeSettings(current, file.jsonPatch);
+        case Ownership.Pipeline:
+        case Ownership.Seed:
+        case Ownership.Generated:
+            return file.content;
+    }
+}
+export async function applyPlan(targetDir, plan, manifest, options) {
+    const outcomes = [];
+    let nextManifest = manifest;
+    const write = async (relativePath, content) => {
+        if (!options.dryRun) {
+            await writeText(join(targetDir, relativePath), content);
+        }
+    };
+    for (const file of plan.files) {
+        const absolute = join(targetDir, file.relativePath);
+        const current = await readTextOrNull(absolute);
+        const desired = await renderFinal(file, current);
+        const record = (kind, note = '') => {
+            outcomes.push(new FileOutcome(file.relativePath, options.dryRun && kind !== OutcomeKind.Unchanged && kind !== OutcomeKind.SeedKept ? OutcomeKind.Planned : kind, note));
+        };
+        if (current === null) {
+            await write(file.relativePath, desired);
+            if (file.ownership === Ownership.Pipeline)
+                nextManifest = nextManifest.with(file.relativePath, sha256(desired));
+            record(OutcomeKind.Created);
+            continue;
+        }
+        if (file.ownership === Ownership.Seed) {
+            record(OutcomeKind.SeedKept);
+            continue;
+        }
+        if (current === desired) {
+            if (file.ownership === Ownership.Pipeline)
+                nextManifest = nextManifest.with(file.relativePath, sha256(desired));
+            record(OutcomeKind.Unchanged);
+            continue;
+        }
+        if (file.ownership !== Ownership.Pipeline) {
+            await write(file.relativePath, desired);
+            record(OutcomeKind.Updated);
+            continue;
+        }
+        const installedSha = manifest.shaFor(file.relativePath);
+        const untouchedSinceInstall = installedSha !== null && installedSha === sha256(current);
+        if (untouchedSinceInstall || options.force) {
+            await write(file.relativePath, desired);
+            nextManifest = nextManifest.with(file.relativePath, sha256(desired));
+            record(OutcomeKind.Updated, options.force && !untouchedSinceInstall ? 'overwritten (--force)' : '');
+            continue;
+        }
+        await write(`${file.relativePath}.incoming`, desired);
+        record(OutcomeKind.Conflict, installedSha === null ? 'existed before install' : 'edited since install');
+    }
+    const obsoletePresent = [];
+    for (const path of plan.obsoletePaths) {
+        if (await pathExists(join(targetDir, path)))
+            obsoletePresent.push(path);
+    }
+    return { report: new ApplyReport(outcomes, obsoletePresent), manifest: nextManifest };
+}

package/dist/src/install/detect.js

@@ -0,0 +1,70 @@
+import { join } from 'node:path';
+import { CanonMapping } from '../domain/canon-mapping.js';
+import { pathExists, readTextOrNull } from '../io/fs.js';
+export class DetectedStack {
+    mapping;
+    isGitRepository;
+    evidence;
+    constructor(mapping, isGitRepository, 
+    /** Human-readable evidence, e.g. "composer.json requires laravel/framework". */
+    evidence) {
+        this.mapping = mapping;
+        this.isGitRepository = isGitRepository;
+        this.evidence = evidence;
+    }
+}
+/** Manifest dependency names only — parse edge for package manifests. */
+async function dependencyNames(path, sections) {
+    const text = await readTextOrNull(path);
+    if (text === null)
+        return [];
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null)
+            return [];
+        const names = [];
+        for (const section of sections) {
+            const block = parsed[section];
+            if (typeof block === 'object' && block !== null) {
+                names.push(...Object.keys(block));
+            }
+        }
+        return names;
+    }
+    catch {
+        return [];
+    }
+}
+export async function detectStack(targetDir) {
+    const isGit = await pathExists(join(targetDir, '.git'));
+    const composer = await dependencyNames(join(targetDir, 'composer.json'), ['require', 'require-dev']);
+    if (composer.includes('laravel/framework')) {
+        return new DetectedStack(CanonMapping.Laravel, isGit, 'composer.json requires laravel/framework');
+    }
+    const npm = await dependencyNames(join(targetDir, 'package.json'), ['dependencies', 'devDependencies']);
+    if (npm.includes('@nestjs/core')) {
+        return new DetectedStack(CanonMapping.NestJs, isGit, 'package.json depends on @nestjs/core');
+    }
+    if (['express', 'fastify', 'hono'].some((name) => npm.includes(name))) {
+        return new DetectedStack(CanonMapping.Express, isGit, 'package.json depends on express/fastify/hono');
+    }
+    const python = [
+        (await readTextOrNull(join(targetDir, 'pyproject.toml'))) ?? '',
+        (await readTextOrNull(join(targetDir, 'requirements.txt'))) ?? '',
+    ].join('\n');
+    if (/\bdjango\b/i.test(python)) {
+        return new DetectedStack(CanonMapping.Django, isGit, 'Python dependencies include django');
+    }
+    if (/\bfastapi\b/i.test(python)) {
+        return new DetectedStack(CanonMapping.FastApi, isGit, 'Python dependencies include fastapi');
+    }
+    if (await pathExists(join(targetDir, 'go.mod'))) {
+        return new DetectedStack(CanonMapping.Go, isGit, 'go.mod present');
+    }
+    const gradle = (await readTextOrNull(join(targetDir, 'build.gradle.kts'))) ?? (await readTextOrNull(join(targetDir, 'build.gradle'))) ?? '';
+    const pom = (await readTextOrNull(join(targetDir, 'pom.xml'))) ?? '';
+    if (/spring-boot/.test(`${gradle}${pom}`)) {
+        return new DetectedStack(CanonMapping.Spring, isGit, 'Spring Boot build file');
+    }
+    return new DetectedStack(null, isGit, 'no recognised backend framework manifest');
+}

package/dist/src/install/managed-section.js

@@ -0,0 +1,35 @@
+export var CommentStyle;
+(function (CommentStyle) {
+    /** Markdown files: <!-- … --> */
+    CommentStyle["Html"] = "html";
+    /** .gitignore and shell-style files: # … */
+    CommentStyle["Hash"] = "hash";
+})(CommentStyle || (CommentStyle = {}));
+const MARK = 'fullstack-agentic-flow';
+function markers(sectionId, style) {
+    switch (style) {
+        case CommentStyle.Html:
+            return { start: `<!-- ${MARK}:${sectionId}:start -->`, end: `<!-- ${MARK}:${sectionId}:end -->` };
+        case CommentStyle.Hash:
+            return { start: `# ${MARK}:${sectionId}:start`, end: `# ${MARK}:${sectionId}:end` };
+    }
+}
+/**
+ * Insert or replace one delimited section in a file the user owns, leaving
+ * everything outside the markers untouched. Idempotent.
+ */
+export function upsertManagedSection(existing, sectionId, body, style) {
+    const { start, end } = markers(sectionId, style);
+    const block = `${start}\n${body.replace(/\n+$/, '')}\n${end}\n`;
+    if (existing === null || existing.length === 0) {
+        return block;
+    }
+    const startAt = existing.indexOf(start);
+    const endAt = existing.indexOf(end);
+    if (startAt >= 0 && endAt > startAt) {
+        const after = existing.slice(endAt + end.length).replace(/^\n/, '');
+        return `${existing.slice(0, startAt)}${block}${after}`;
+    }
+    const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+    return `${existing}${separator}${block}`;
+}

package/dist/src/install/manifest.js

@@ -0,0 +1,63 @@
+import { join } from 'node:path';
+import { readTextOrNull, writeText } from '../io/fs.js';
+export class ManifestEntry {
+    path;
+    sha256;
+    constructor(path, sha256) {
+        this.path = path;
+        this.sha256 = sha256;
+    }
+}
+/** `.ai-agents/.install-manifest.json` — the checksum each pipeline file had when we last wrote it. */
+export class InstallManifest {
+    pipelineVersion;
+    entries;
+    static RELATIVE_PATH = '.ai-agents/.install-manifest.json';
+    constructor(pipelineVersion, entries) {
+        this.pipelineVersion = pipelineVersion;
+        this.entries = entries;
+    }
+    shaFor(path) {
+        return this.entries.find((entry) => entry.path === path)?.sha256 ?? null;
+    }
+    with(path, sha) {
+        const others = this.entries.filter((entry) => entry.path !== path);
+        return new InstallManifest(this.pipelineVersion, [...others, new ManifestEntry(path, sha)]);
+    }
+    withVersion(pipelineVersion) {
+        return new InstallManifest(pipelineVersion, this.entries);
+    }
+    /**
+     * @param fallback used when the repository has no manifest yet — e.g. the
+     *   published checksums of pipeline v1, so pristine v1 files upgrade in place.
+     */
+    static async load(targetDir, fallback) {
+        const text = await readTextOrNull(join(targetDir, InstallManifest.RELATIVE_PATH));
+        return text === null ? fallback : InstallManifest.parse(text);
+    }
+    static async loadFile(path) {
+        const text = await readTextOrNull(path);
+        return text === null ? new InstallManifest('none', []) : InstallManifest.parse(text);
+    }
+    /** Parse edge for manifest JSON (typed-data T5). */
+    static parse(text) {
+        const raw = JSON.parse(text);
+        if (typeof raw !== 'object' || raw === null)
+            return new InstallManifest('none', []);
+        const record = raw;
+        const files = Array.isArray(record.files) ? record.files : [];
+        const entries = files.flatMap((item) => {
+            if (typeof item !== 'object' || item === null)
+                return [];
+            const entry = item;
+            return typeof entry.path === 'string' && typeof entry.sha256 === 'string'
+                ? [new ManifestEntry(entry.path, entry.sha256)]
+                : [];
+        });
+        return new InstallManifest(typeof record.pipelineVersion === 'string' ? record.pipelineVersion : 'none', entries);
+    }
+    async save(targetDir) {
+        const sorted = [...this.entries].sort((a, b) => a.path.localeCompare(b.path));
+        await writeText(join(targetDir, InstallManifest.RELATIVE_PATH), `${JSON.stringify({ pipelineVersion: this.pipelineVersion, files: sorted }, null, 2)}\n`);
+    }
+}

package/dist/src/install/planned-file.js

@@ -0,0 +1,77 @@
+/** Who owns a file after installation, which decides how update treats it. */
+export var Ownership;
+(function (Ownership) {
+    /** Shipped by the pipeline; refreshed on update unless the team edited it. */
+    Ownership["Pipeline"] = "pipeline";
+    /** Written once as a starting point; the team or an agent owns it afterwards. */
+    Ownership["Seed"] = "seed";
+    /** Regenerated from the installer's choices on every run. */
+    Ownership["Generated"] = "generated";
+    /** A delimited section inside a file the team owns (CLAUDE.md, AGENTS.md, .gitignore). */
+    Ownership["ManagedSection"] = "managed-section";
+    /** Keys merged into a JSON settings file the team owns. */
+    Ownership["JsonMerge"] = "json-merge";
+})(Ownership || (Ownership = {}));
+export class PlannedFile {
+    relativePath;
+    ownership;
+    content;
+    sectionId;
+    commentStyle;
+    jsonPatch;
+    constructor(relativePath, ownership, 
+    /** Full content for Pipeline/Seed/Generated; section body for ManagedSection. */
+    content, sectionId, commentStyle, jsonPatch) {
+        this.relativePath = relativePath;
+        this.ownership = ownership;
+        this.content = content;
+        this.sectionId = sectionId;
+        this.commentStyle = commentStyle;
+        this.jsonPatch = jsonPatch;
+    }
+    static pipeline(relativePath, content) {
+        return new PlannedFile(relativePath, Ownership.Pipeline, content, null, null, null);
+    }
+    static seed(relativePath, content) {
+        return new PlannedFile(relativePath, Ownership.Seed, content, null, null, null);
+    }
+    static generated(relativePath, content) {
+        return new PlannedFile(relativePath, Ownership.Generated, content, null, null, null);
+    }
+    static section(relativePath, sectionId, body, style) {
+        return new PlannedFile(relativePath, Ownership.ManagedSection, body, sectionId, style, null);
+    }
+    static settings(relativePath, patch) {
+        return new PlannedFile(relativePath, Ownership.JsonMerge, '', null, null, patch);
+    }
+}
+export class MarketplaceSource {
+    name;
+    githubRepo;
+    constructor(name, githubRepo) {
+        this.name = name;
+        this.githubRepo = githubRepo;
+    }
+}
+/** The keys this installer adds to `.claude/settings.json`; everything else in the file is preserved. */
+export class ClaudeSettingsPatch {
+    marketplaces;
+    enabledPlugins;
+    constructor(marketplaces, enabledPlugins) {
+        this.marketplaces = marketplaces;
+        this.enabledPlugins = enabledPlugins;
+    }
+    isEmpty() {
+        return this.marketplaces.length === 0 && this.enabledPlugins.length === 0;
+    }
+}
+export class FilePlan {
+    files;
+    obsoletePaths;
+    constructor(files, 
+    /** Paths from older pipeline versions that should be removed by hand. */
+    obsoletePaths) {
+        this.files = files;
+        this.obsoletePaths = obsoletePaths;
+    }
+}

package/dist/src/install/planner.js

@@ -0,0 +1,139 @@
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { ClaudeMdMode } from '../domain/claude-md-mode.js';
+import { Runtime } from '../domain/runtime.js';
+import { isSplit } from '../domain/topology.js';
+import { ToolId } from '../domain/tool.js';
+import { COMMAND_CATALOG } from '../registry/commands.js';
+import { SUBAGENT_CATALOG } from '../registry/subagents.js';
+import { TOOL_CATALOG } from '../registry/tools.js';
+import { listFilesRecursive, pathExists } from '../io/fs.js';
+import { renderClaudeCommand, renderClaudeSubagent, renderCodexSkill } from './adapters.js';
+import { CommentStyle } from './managed-section.js';
+import { ClaudeSettingsPatch, FilePlan, MarketplaceSource, PlannedFile } from './planned-file.js';
+import { rulesPresetFor } from './rules-preset.js';
+import { renderSetupGuide } from './setup-guide.js';
+export class InstallChoices {
+    topology;
+    runtimes;
+    tools;
+    mapping;
+    claudeMd;
+    constructor(topology, runtimes, tools, mapping, claudeMd = ClaudeMdMode.Import) {
+        this.topology = topology;
+        this.runtimes = runtimes;
+        this.tools = tools;
+        this.mapping = mapping;
+        this.claudeMd = claudeMd;
+    }
+    has(tool) {
+        return this.tools.includes(tool);
+    }
+    targets(runtime) {
+        return this.runtimes.includes(runtime);
+    }
+}
+/** Files under payload/ai-agents that the team owns after the first install. */
+const SEED_PATHS = ['state/current-stage.md'];
+/** Paths shipped by pipeline v1 that v2 renamed or removed. */
+const OBSOLETE_PATHS = [
+    '.ai-agents/agents/02d-api-seam.md',
+    '.claude/agents/api-seam.md',
+    '.ai-agents/state/contract-api.md',
+];
+function commandIndex(runtime) {
+    return COMMAND_CATALOG.all()
+        .map((command) => {
+        const invocation = runtime === Runtime.ClaudeCode ? `/${command.slug}` : `$flow-${command.slug}`;
+        return `- \`${invocation}\` — ${command.description}`;
+    })
+        .join('\n');
+}
+/**
+ * One section, in AGENTS.md, covering every installed runtime — Codex reads it
+ * directly and so does Claude Code, which loads AGENTS.md when the repository
+ * has no CLAUDE.md (and through the `@AGENTS.md` import stub otherwise).
+ */
+async function pipelineSection(payloadDir, choices) {
+    const base = (await readFile(join(payloadDir, 'root', 'pipeline-section.md'), 'utf8')).replace(/\n+$/, '');
+    const parts = [base, ''];
+    for (const runtime of choices.runtimes) {
+        const label = runtime === Runtime.ClaudeCode ? 'In Claude Code' : 'In Codex';
+        parts.push(`${label}:`, '', commandIndex(runtime), '');
+    }
+    if (choices.targets(Runtime.Codex)) {
+        parts.push('Codex has no subagent files: when a command says to run agents in parallel,', 'run them as separate sessions or one after another, each reading its own file', 'in `.ai-agents/agents/`.');
+    }
+    if (choices.has(ToolId.TaskObserver)) {
+        parts.push('', '**task-observer**: load the task-observer skill before the first tool call of', 'every session. Write observation logs to `.ai-agents/observations/` and', 'proposed updates to `.ai-agents/observations/proposals/`. Never edit agent', 'files or the architecture context from an observation.');
+    }
+    return parts.join('\n');
+}
+function claudeSettingsPatch(choices) {
+    const marketplaces = [];
+    const plugins = [];
+    if (choices.has(ToolId.Superpowers)) {
+        plugins.push('superpowers@claude-plugins-official');
+    }
+    if (choices.has(ToolId.Ponytail)) {
+        marketplaces.push(new MarketplaceSource('ponytail', 'DietrichGebert/ponytail'));
+        plugins.push('ponytail@ponytail');
+    }
+    return new ClaudeSettingsPatch(marketplaces, plugins);
+}
+/**
+ * Claude Code loads AGENTS.md only when the repository has no CLAUDE.md, and an
+ * `@AGENTS.md` import is never loaded twice — so this stub is safe either way,
+ * and it is the only thing that works in sessions where direct AGENTS.md
+ * support is unavailable (Bedrock, telemetry off, pre-2.1.277).
+ */
+const CLAUDE_MD_IMPORT = [
+    '@AGENTS.md',
+    '',
+    'The delivery pipeline section lives in AGENTS.md so Claude Code and Codex read',
+    'the same file. Edit it there, not here.',
+].join('\n');
+export async function buildPlan(payloadDir, config, targetDir, claudeMd) {
+    const choices = new InstallChoices(config.topology, config.runtimes, config.tools, config.mapping, claudeMd);
+    const files = [];
+    const agentsRoot = join(payloadDir, 'ai-agents');
+    for (const relative of await listFilesRecursive(agentsRoot)) {
+        const content = await readFile(join(agentsRoot, relative), 'utf8');
+        const target = `.ai-agents/${relative}`;
+        files.push(SEED_PATHS.includes(relative) ? PlannedFile.seed(target, content) : PlannedFile.pipeline(target, content));
+    }
+    files.push(PlannedFile.generated('.ai-agents/pipeline.config.json', config.toJson()));
+    files.push(PlannedFile.seed('.ai-agents/rules.config.json', rulesPresetFor(choices.mapping).toJson()));
+    files.push(PlannedFile.generated('.ai-agents/SETUP.md', renderSetupGuide(choices, TOOL_CATALOG)));
+    if (isSplit(choices.topology)) {
+        files.push(PlannedFile.seed('contracts/README.md', await readFile(join(payloadDir, 'root', 'contracts-README.md'), 'utf8')));
+    }
+    for (const command of COMMAND_CATALOG.all()) {
+        const body = await readFile(join(payloadDir, 'commands', `${command.slug}.md`), 'utf8');
+        if (choices.targets(Runtime.ClaudeCode)) {
+            files.push(PlannedFile.pipeline(`.claude/commands/${command.slug}.md`, renderClaudeCommand(command, body)));
+        }
+        if (choices.targets(Runtime.Codex)) {
+            files.push(PlannedFile.pipeline(`.agents/skills/flow-${command.slug}/SKILL.md`, renderCodexSkill(command, body)));
+        }
+    }
+    files.push(PlannedFile.section('AGENTS.md', 'pipeline', await pipelineSection(payloadDir, choices), CommentStyle.Html));
+    if (choices.targets(Runtime.ClaudeCode)) {
+        for (const agent of SUBAGENT_CATALOG.all()) {
+            files.push(PlannedFile.pipeline(`.claude/agents/${agent.name}.md`, renderClaudeSubagent(agent)));
+        }
+        const claudeMdExists = await pathExists(join(targetDir, 'CLAUDE.md'));
+        if (choices.claudeMd === ClaudeMdMode.Import || claudeMdExists) {
+            files.push(PlannedFile.section('CLAUDE.md', 'pipeline', CLAUDE_MD_IMPORT, CommentStyle.Html));
+        }
+        const patch = claudeSettingsPatch(choices);
+        if (!patch.isEmpty()) {
+            files.push(PlannedFile.settings('.claude/settings.json', patch));
+        }
+    }
+    const ignored = TOOL_CATALOG.forIds(choices.tools).flatMap((tool) => tool.ignorePaths);
+    if (ignored.length > 0) {
+        files.push(PlannedFile.section('.gitignore', 'tools', ignored.join('\n'), CommentStyle.Hash));
+    }
+    return new FilePlan(files, OBSOLETE_PATHS);
+}

package/dist/src/install/rules-preset.js

@@ -0,0 +1,37 @@
+import { CanonMapping } from '../domain/canon-mapping.js';
+/** Starting values for .ai-agents/rules.config.json; /bootstrap narrows them against real history. */
+export class RulesPreset {
+    typedBoundaryPaths;
+    sourcePaths;
+    testPaths;
+    constructor(typedBoundaryPaths, sourcePaths, testPaths) {
+        this.typedBoundaryPaths = typedBoundaryPaths;
+        this.sourcePaths = sourcePaths;
+        this.testPaths = testPaths;
+    }
+    toJson() {
+        return `${JSON.stringify({
+            typedBoundaries: { paths: this.typedBoundaryPaths, allow: [] },
+            testWithChange: { sourcePaths: this.sourcePaths, testPaths: this.testPaths, exemptionTag: 'no-test' },
+        }, null, 2)}\n`;
+    }
+}
+export function rulesPresetFor(mapping) {
+    switch (mapping) {
+        case CanonMapping.Laravel:
+            return new RulesPreset(['app/Modules/*/Domain/**', 'app/Modules/*/Application/**'], ['app/Modules/**'], ['tests/**']);
+        case CanonMapping.NestJs:
+        case CanonMapping.Express:
+            return new RulesPreset(['src/modules/*/domain/**', 'src/modules/*/application/**'], ['src/modules/**'], ['**/*.spec.ts', '**/*.test.ts', 'test/**']);
+        case CanonMapping.Django:
+        case CanonMapping.FastApi:
+            return new RulesPreset(['**/modules/*/domain/**', '**/modules/*/application/**'], ['**/modules/**'], ['**/tests/**', '**/test_*.py']);
+        case CanonMapping.Spring:
+        case CanonMapping.Go:
+        case CanonMapping.Custom:
+        case null:
+            // The typed-boundaries checker covers PHP, TypeScript and Python; other
+            // stacks rely on their compiler plus review. /bootstrap fills these in.
+            return new RulesPreset([], [], []);
+    }
+}

package/dist/src/install/setup-guide.js

@@ -0,0 +1,60 @@
+import { Runtime } from '../domain/runtime.js';
+import { StepLocation } from '../domain/tool.js';
+import { Topology, describeTopology } from '../domain/topology.js';
+const runtimeLabel = (runtime) => (runtime === Runtime.ClaudeCode ? 'Claude Code' : 'Codex');
+function stepLine(step) {
+    const where = step.location === StepLocation.Shell ? 'shell' : 'inside the agent';
+    const check = step.verified ? '' : ' _(unverified: closest documented form — confirm against the tool README)_';
+    return `- [ ] ${step.description} (${where}):\n  \`${step.command}\`${check}`;
+}
+function toolBlock(tool, runtimes) {
+    const lines = [`### ${tool.name}`, '', `${tool.purpose}`, '', `Source: \`${tool.source}\` · Used by: ${tool.usedBy.join(', ')}`, ''];
+    for (const runtime of runtimes) {
+        const support = tool.supportFor(runtime);
+        if (support === null) {
+            lines.push(`**${runtimeLabel(runtime)}**: not supported — skip.`, '');
+            continue;
+        }
+        lines.push(`**${runtimeLabel(runtime)}**`, '', ...support.steps.map(stepLine));
+        if (support.caveat.length > 0)
+            lines.push('', `> ${support.caveat}`);
+        lines.push('');
+    }
+    if (tool.usage.length > 0) {
+        lines.push('Day to day:', '', ...tool.usage.map((line) => `- ${line}`), '');
+    }
+    return lines.join('\n');
+}
+function nextStep(topology) {
+    const seam = topology === Topology.SplitFrontend
+        ? '\nThis is a `split-frontend` repo: before the first feature, import its contract with `/seam import {path-or-url}`.'
+        : '';
+    return [
+        '## Then',
+        '',
+        '- Empty repository, or only framework defaults → `/scaffold`, review the slice, then `/bootstrap`',
+        '- Existing code → `/bootstrap`',
+        '- After bootstrap: `/intake` → `/impact` → `/contract` → `/sequence` → `/implement` …',
+        seam,
+    ].join('\n');
+}
+/** `.ai-agents/SETUP.md` — the per-repo checklist for everything the file copy cannot do. */
+export function renderSetupGuide(choices, catalog) {
+    const tools = catalog.forIds(choices.tools);
+    const header = [
+        '# Pipeline setup',
+        '',
+        '_Generated by `fullstack-agentic-flow`. Regenerated on every `init`/`update`; edit `.ai-agents/toolchain.md` instead._',
+        '',
+        `**Topology**: ${describeTopology(choices.topology)}`,
+        `**Runtimes**: ${choices.runtimes.map(runtimeLabel).join(', ')}`,
+        `**Canon mapping**: ${choices.mapping ?? 'not detected — /scaffold or /bootstrap records it'}`,
+        '',
+        'Check with `npx fullstack-agentic-flow doctor`.',
+        '',
+    ];
+    const body = tools.length === 0
+        ? ['## Tools', '', 'None selected. Add later with `npx fullstack-agentic-flow init --tools …` (existing files are respected).', '']
+        : ['## Tools', '', 'Shell steps can be run by the installer with `--run-tools`; steps marked _inside the agent_ need you.', '', ...tools.map((tool) => toolBlock(tool, choices.runtimes))];
+    return `${[...header, ...body, nextStep(choices.topology)].join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n+$/, '')}\n`;
+}

package/dist/src/io/fs.js

@@ -0,0 +1,39 @@
+import { readFile, writeFile, mkdir, access, readdir, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, join, relative, sep } from 'node:path';
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readTextOrNull(path) {
+    return (await pathExists(path)) ? readFile(path, 'utf8') : null;
+}
+export async function writeText(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, 'utf8');
+}
+export function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/** Every file under `root`, as forward-slash paths relative to `root`, sorted. */
+export async function listFilesRecursive(root) {
+    const found = [];
+    const walk = async (dir) => {
+        for (const entry of await readdir(dir)) {
+            const full = join(dir, entry);
+            if ((await stat(full)).isDirectory()) {
+                await walk(full);
+            }
+            else {
+                found.push(relative(root, full).split(sep).join('/'));
+            }
+        }
+    };
+    await walk(root);
+    return found.sort();
+}